% -*- Mode:TeX -*-
%%% 
%%% TEXAS INSTRUMENTS  INCORPORATED,  P.O.  BOX  2909,  AUSTIN,  TEXAS 78769
%%% Copyright (C) 1988, Texas Instruments Incorporated.  All Rights Reserved.
%%% 
%%%     Permission is granted to any individual or institution to use,
%%%     copy, modify and distribute this document, provided that  this
%%%     complete  copyright  and   permission  notice   is maintained,
%%%     intact, in  all  copies  and  supporting documentation.  Texas
%%%     Instruments Incorporated  makes  no  representations about the
%%%     suitability of the software described herein for any  purpose.
%%%     It is provided "as is" without express or implied warranty.
%
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                 %
%                            Preamble                             %
%                                                                 %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\documentstyle[twoside]{report}
\pagestyle{headings}
%%
%% Inserted from home:/usr/local/hacks/tex/setmargins.tex:
%%
%%    Original: Glenn Manuel 12-17-86
%%    Added optional [printer-offset]: Glenn Manuel 2-27-87
%% Sets the margins, taking into account the fact that LaTex
%% likes to start the left margin 1.0 inch from the left edge
%% of the paper.
%%   This macro prints on the screen and in the log file
%%   the values it sets for:
%%     Textwidth, Odd Page Left Margin, Even Page Left Margin,
%%     Marginparwidth, Printer Offset
%%     (the values are in points: 72.27 pts/inch).
%%     The Odd and Even Page Left Margins include LaTeX's
%%     built-in 1.0in offset, but NOT the [printer-offset],
%%     so these values always indicate what the actual
%%     printout SHOULD measure.
%%
%% USAGE:  Place the following between the
%%         \documentstyle   and  \begin{document} commands:
%% \input{this-file's-name}
%% \setmargins[printer-offset]{line-length}{inside-margin-width}
%%
%%   where ALL arguments to \setmargins are DIMENSIONS
%%           like {6.5in}, {65pt}, {23cm}, etc.
%%   The units MUST BE SUPPLIED, even if the dimension is zero {0in}.
%%
%%   [printer-offset] is optional.  Default is zero.
%%
%%   Examples:
%% \setmargins{0in}{0in}         % default line length & default margins
%% \setmargins[-.12in]{0in}{0in} % compensate for printer offset
%% \setmargins{0in}{1in}         % default line length, 1 inch inner margin
%% \setmargins{6.5in}{0in}       % 6.5 inch line length & default margins
%% \setmargins{5in}{1.5in}       % 5 inch line length & 1.5 inch inner margin
%%
%%   {inside-margin-width} is defined as follows:
%%       For 1-sided printing: left margin for all pages.
%%       For 2-sided printing: left  margin for odd pages,
%%                             right margin for even pages.
%%
%%   Defaults:
%%   Each argument has a default if {0in} is used as the argument:
%%      line-length default = 6.0in
%%      inside-margin-width default:
%%         For 1-sided printing, text is centered on the page
%%                     (each margin = [1/2]*[8.5in - line length]);
%%         For 2-sided printing, inside margin is twice the outside margin
%%                     (inside  margin = [2/3]*[8.5in - line length],
%%                      outside margin = [1/3]*[8.5in - line length]).
%%      printer-offset default = 0in
%%
%%  For all cases, the outside margin (and marginparwidth, the
%%  width of margin notes) is just whatever is left over after
%%  accounting for the inside margin and the line length.
%%
%% Note: LaTeX's built-in offset of 1.0 inch can vary somewhat,
%%       depending upon the alignment of the Laser printer.
%%       If you need it to be EXACT, you will have to supply
%%       the optional [printer-offset] argument.
%%       Subtract the actual measured left margin on an
%%       odd-numbered page from the printed Odd Page Left Margin
%%       value, and use the result as the [printer-offset].
%%       Positive values shift everything to the right,
%%       negative values shift everything to the left.
%%
\makeatletter
\def\setmargins{\@ifnextchar[{\@setmargins}{\@setmargins[0in]}}
\def\@setmargins[#1]#2#3{
%%%  Uses temporary dimension registers \dimen0, \dimen2, \dimen3, \dimen1
    \dimen1=#1                         % 1st argument [printer offset]
    \dimen2=#2                         % 2nd argument (line length)
    \dimen3=#3                         % 3rd argument (inner margin)
     \advance\dimen1 by -1.0in         % for LaTeX built-in offset
    \ifdim\dimen2=0in 
        \textwidth=6in  \dimen2=6in
    \else \textwidth=\dimen2
    \fi
    \dimen0=8.5in
    \advance\dimen0 by -\dimen2         % 8.5in - line length
    \if@twoside
       \ifdim\dimen3=0in  % use defaults: 2/3 inside, 1/3 outside
          \divide\dimen0 by 3           % (8.5in-line length)/3
          \dimen2=2\dimen0              % (2/3)*(8.5in-line length)
          \oddsidemargin=\dimen2
          \advance\oddsidemargin by \dimen1   % add in offset
          \dimen2=\dimen0               % (8.5in-line length)/3
          \evensidemargin=\dimen2
          \advance\evensidemargin by \dimen1  % add in offset
%  allow for space on each side of marginal note
          \advance\dimen0 by -2\marginparsep
          \marginparwidth=\dimen0
       \else            % use supplied 2-sided value
          \oddsidemargin=\dimen3             % inside-margin-width
          \advance\oddsidemargin by \dimen1  % add in offset
          \advance\dimen0 by -\dimen3   % 8.5in-line length-inside margin
          \evensidemargin=\dimen0
          \advance\evensidemargin by \dimen1 % add in offset
%  allow for space on each side of marginal note
          \advance\dimen0 by -2\marginparsep
          \marginparwidth=\dimen0
       \fi
%  one-sided
    \else \ifdim\dimen3=0in  % use defaults: center text 
              \divide\dimen0 by 2         % (8.5in-line length)/2
              \oddsidemargin=\dimen0      % (8.5in-line length)/2
              \advance\oddsidemargin by \dimen1   % add in offset
              \evensidemargin=\dimen0     % (8.5in-line length)/2
              \advance\evensidemargin by \dimen1  % add in offset
%  allow for space on each side of marginal note
              \advance\dimen0 by -2\marginparsep
              \marginparwidth=\dimen0
          \else  % use supplied values
              \advance\dimen0 by -\dimen3  % 8.5in-line length-left margin
%  allow for space on each side of marginal note
              \advance\dimen0 by -2\marginparsep
              \marginparwidth=\dimen0
              \advance\dimen3 by \dimen1   % add in offset
              \oddsidemargin=\dimen3
              \evensidemargin=\dimen3
          \fi
    \fi
  \immediate\write16{Textwidth = \the\textwidth}
  \dimen0=1.0in
  \advance\dimen0 by \oddsidemargin
  \immediate\write16{Odd Page Left Margin = \the\dimen0}
  \dimen0=1.0in
  \advance\dimen0 by \evensidemargin
  \immediate\write16{Even Page Left Margin = \the\dimen0}
  \immediate\write16{Marginparwidth = \the\marginparwidth}
  \dimen0=#1
  \immediate\write16{Printer Offset = \the\dimen0}
 }
%
\def\@outputpage{\begingroup\catcode`\ =10 \if@specialpage 
     \global\@specialpagefalse\@nameuse{ps@\@specialstyle}\fi
     \if@twoside 
       \ifodd\count\z@ \let\@thehead\@oddhead \let\@thefoot\@oddfoot
                       \let\@themargin\oddsidemargin
% treat page 0 (title page) as if it is an odd-numbered page
        \else \ifnum\count\z@=0 \let\@thehead\@oddhead \let\@thefoot\@oddfoot
                                \let\@themargin\oddsidemargin
              \else \let\@thehead\@evenhead
                    \let\@thefoot\@evenfoot \let\@themargin\evensidemargin
     \fi\fi\fi
     \shipout
     \vbox{\normalsize \baselineskip\z@ \lineskip\z@
           \vskip \topmargin \moveright\@themargin
           \vbox{\setbox\@tempboxa
                   \vbox to\headheight{\vfil \hbox to\textwidth{\@thehead}}
                 \dp\@tempboxa\z@
                 \box\@tempboxa
                 \vskip \headsep
                 \box\@outputbox
                 \baselineskip\footskip
                 \hbox to\textwidth{\@thefoot}}}\global\@colht\textheight
           \endgroup\stepcounter{page}\let\firstmark\botmark}
%
\makeatother
%%
%% End of home:/usr/local/hacks/tex/setmargins.tex:
%%
\setmargins{6.5in}{1in}
\topmargin = 0in
\headheight = 5mm
\headsep = 3mm
\textheight = 9in
%\textwidth = 5.9in
\makeindex
\begin{document}
% Simple command to generate the index.
\newcommand{\outputindex}[1]{{
\begin{theindex}
\input{#1}
\end{theindex}
}}
%%
%% Inserted from home:/u3/ekberg/tex/pretxt.tex
%%
% Define the old PRETXT SAME/HIGHER/LOWER commands.
% These let one move up and down in the dot level numbering
% system without having to know the current level.  Note that the L
% version of the macro exists to allow one to specify a label for the
% section information.
%
% If you didn't understand the above, then read on.  PRETXT is the
% name of a preprocessor for another word processor which added some
% interesting features.  The feature implemented here, is an improved
% numbering scheme based upon the existing numbering scheme available
% in LaTeX.  The improvement is that one need not remember which level
% you are at when defining a new section, one only need remember the
% relative ordering.  For example:
%   LaTeX input                          LaTeX output
%   \CHAPTER{Foo}                          1
%   \LOWER{Foo Bar}                        1.1
%   \LOWER{Foo Bar Baz}                    1.1.1
%   \SAME{More Foo Bar}                    1.1.2
%   \SAME{Even More Foo Bar}               1.1.3
%   \HIGHER{More Foo}                      1.2
%   \SAME{Even More Foo}                   1.3
%   \LOWER{Even More Even more Foo}        1.3.1
% The advantage here is that one can reorganize entire sections of
% text and only have to change one of the section numbering commands
% (the first one).  With the original LaTeX method, one would have to
% change every section numbering command if one moved to a different
% level in the hierarchy.
%
% These four commands have alternates which allow one to specify a
% label for the section number and its page.  This allows one to refer
% to that number elsewhere in the document.  The alternates are
% CHAPTERL, LOWERL, SAMEL and HIGHERL.
%
\countdef\sectionlevel=100
\global\sectionlevel=0
\newcommand{\CHAPTER}[1]{\global\sectionlevel=0 \chapter{#1}
}
\newcommand{\CHAPTERL}[2]{\global\sectionlevel=0 \chapter{#1} \label{#2}
}
\newcommand{\SAME}[1]{
 \ifnum\sectionlevel=0 {\global\sectionlevel=0 {\chapter{#1}}}
 \else\ifnum\sectionlevel=1 {\bigskip \section{#1}}
      \else\ifnum\sectionlevel=2 {\bigskip \subsection{#1}}
           \else {\bigskip \subsubsection{#1}}
           \fi
      \fi
 \fi}
\newcommand{\SAMEL}[2]{
 \ifnum\sectionlevel=0 {\global\sectionlevel=0 {\chapter{#1} \label{#2}}}
 \else\ifnum\sectionlevel=1 {\bigskip \section{#1} \label{#2}}
      \else\ifnum\sectionlevel=2 {\bigskip \subsection{#1} \label{#2}}
           \else {\bigskip \subsubsection{#1} \label{#2}}
           \fi
      \fi
 \fi}
\newcommand{\LOWER}[1]{{\global\advance\sectionlevel by1}
 \ifnum\sectionlevel=0 {\global\sectionlevel=0 {\chapter{#1}}}
 \else\ifnum\sectionlevel=1 {\bigskip \section{#1}}
      \else\ifnum\sectionlevel=2 {\bigskip \subsection{#1}}
           \else {\bigskip \subsubsection{#1}}
           \fi
      \fi
 \fi}
\newcommand{\LOWERL}[2]{{\global\advance\sectionlevel by1}
 \ifnum\sectionlevel=0 {\global\sectionlevel=0 {\chapter{#1} \label{#2}}}
 \else\ifnum\sectionlevel=1 {\bigskip \section{#1} \label{#2}}
      \else\ifnum\sectionlevel=2 {\bigskip \subsection{#1} \label{#2}}
           \else {\bigskip \subsubsection{#1} \label{#2}}
           \fi
      \fi
 \fi}
\newcommand{\HIGHER}[1]{{\global\advance\sectionlevel by-1}
 \ifnum\sectionlevel=0 {\global\sectionlevel=0 {\chapter{#1}}}
 \else\ifnum\sectionlevel=1 {\bigskip \section{#1}}
      \else\ifnum\sectionlevel=2 {\bigskip \subsection{#1}}
           \else {\bigskip \subsubsection{#1}}
           \fi
      \fi
 \fi}
\newcommand{\HIGHERL}[2]{{\global\advance\sectionlevel by-1}
 \ifnum\sectionlevel=0 {\global\sectionlevel=0 {\chapter{#1} \label{#2}}}
 \else\ifnum\sectionlevel=1 {\bigskip \section{#1} \label{#2}}
      \else\ifnum\sectionlevel=2 {\bigskip \subsection{#1} \label{#2}}
           \else {\bigskip \subsubsection{#1} \label{#2}}
           \fi
      \fi
 \fi}
%%
%% End of home:/u3/ekberg/tex/pretxt.tex
%%
\setlength{\parskip}{5 mm}
\setlength{\parindent}{0 in}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                 %
%                            Document                             %
%                                                                 %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%
\title{Common Lisp User Interface Environment}
\author{Kerry Kimbrough \\
LaMott Oren \\ \\
Texas Instruments Incorporated} 
\date{Version 6.0\\
July 10, 1989 \\[2 in]
\copyright 1987, 1988, 1989\  Texas Instruments Incorporated\\[.5in]
\parbox{3.5in}{
     Permission is granted to any individual or institution to use,
     copy, modify and distribute this document, provided that  this
     complete  copyright  and   permission  notice   is maintained,
     intact, in  all  copies  and  supporting documentation.  Texas
     Instruments Incorporated  makes  no  representations about the
     suitability of the software described herein for any  purpose.
     It is provided ``as is'' without express or implied warranty.
}}
\maketitle
\setcounter{page}{1}
\pagenumbering{roman}
\tableofcontents
\clearpage
\listoffigures
\clearpage
\setcounter{page}{0}
\pagenumbering{arabic}

%
\CHAPTER{Introduction}
This document describes the Common Lisp User Interface Environment (CLUE), a
portable system for user interface programming in Common Lisp.
CLUE is based on the X Window System\cite{x-window-system} and extends X to
provide an architectural model for the construction of interactive
Lisp applications.
In this model, a user interface is composed of a set of abstract interface
objects.  CLUE defines the basic programmer interfaces for defining
interface object types, creating interface
objects, and using them to control the dialog between the application and its
human user.  
%
\LOWER{Goals}
{\bf Portable}
\begin{quote}
Applications which use CLUE should be easily portable to any hardware/software
environment which provides an implementation of CLUE and CLX\index{CLX}\cite{clx},
the Common Lisp programmer's interface to the X Window System.  CLUE
itself should be a portable software system written in Common Lisp\cite{cltl}.
\end{quote}
%
{\bf Flexible}
\begin{quote}
CLUE is intended to support the development of a wide variety of user interface
styles. In particular, it should be possible to use CLUE to implement any of the
user interfaces found in current Lisp development environments. Both
graphical and textual interfaces should be easy to create. In order to achieve
this goal, CLUE is
``policy-free''. That is, decisions about user interface style --- the look,
feel, consistency, and techniques of the interface --- are left to the user
interface programmer.
\end{quote}
%
{\bf Extensible}
\begin{quote}
CLUE should provide the ability to define and deploy new types of user
interface objects which refine and extend the behavior of more basic
object types. CLUE provides this ability through the methodology
of object-oriented programming.  
\end{quote} 
%
{\bf Modular}
\begin{quote}
CLUE should comprise a well-defined and self-sufficient layer of the
user interface programming system. Using
CLUE, an
application programmer should be able to implement most types of user
interfaces without accessing underlying software layers and without knowledge of the
implementation internals of CLUE objects.
\end{quote} {\bf Compatible}
\begin{quote}
CLUE must be compatible with related software systems which will be
separately standardized. 
CLUE is based on the X Window System
\index{X Window System} which,
because of its wide distribution and broad support, constitutes a {\it de facto}
standard\footnotemark.
CLUE should be consistent with future Common Lisp standards for object-oriented programming.
Therefore, CLUE is based on the proposed Common Lisp Object System
(CLOS)
\index{CLOS}\cite{clos}.
\end{quote}
\footnotetext{X is also
being considered by ANSI for a proposed national standard for display
management.}
%
%
\SAME{Overview}
\LOWER{Contacts}
%
In CLUE, the basis for programming the user interface of an application
program is object-oriented programming --- creating objects called
{\bf contacts}\index{contact} and invoking their methods.  

An interactive application program can be considered to consist of a collection
of functions,  some of which perform the processing that is essential
to the application's purpose (e.g.\ text editing, knowledge base management,
etc.).  Other functions exist solely for the purpose of communicating with
the application's human user.  In CLUE, such human interface functions are
represented by objects known as {\bf contacts}.  Contacts are responsible for
presenting application information to the user on the display screen and for
informing the application of input sent by the user via interactive input
devices (such as the keyboard and the pointer).  A contact generally embodies a
component of the user interface that knows how to:
\begin{itemize}
\item  display its contents,
\item process input events that are directed to it, and 
\item report its results (if any) back to the application.
\end{itemize}

A contact provides a relatively high-level abstraction for user interface
programming.  The purpose of such an abstraction is twofold: 
\begin{itemize}	
\item To simplify and raise the level of the dialog between the application and
the user. A contact insulates the application programmer from the detailed behavior
of a user interface component (displaying its contents, acquiring its input,
etc.). As an ``agent'' of the application, a contact can direct 
communication with the user in terms closer to the application's domain.

\item To define a uniform framework within which many different types of user
interface objects can be combined. The contact class raises to a higher level the
commonality between a great variety of interface objects --- menus, forms,
dials, scroll bars, buttons, dialog boxes, text entry, etc.
\end{itemize}

Because CLUE is an object-oriented programming system, it is described
in terms of the proposed standard
Common Lisp Object System (CLOS)\index{CLOS}\cite{clos}. The CLUE
specification thus
consists primarily of a set of CLOS classes, generic functions, and methods. 


The subclassing and inheritance properties of CLOS are
important to the use of contacts. A contact (sub)class implements a
specific interface technique (for input, output, or both) and a specific
presentation style. Thus, a contact subclass
can represent either an extension in technique (e.g.\ a hierarchical-pop-up-menu
subclass of a pop-up-menu class) or a variation in style only (e.g.\ a
drop-shadow-pop-up-menu subclass). This is expected to lead to the development
of contact ``libraries'', providing a rich repertoire of interface
techniques and a choice of several functionally-interchangeable styles.

\SAMEL{The User Interface Programming System}{ch:uips}

As defined by CLUE, contact objects represent an intermediate level of
abstraction within a larger user interface programming system.
CLUE relies upon the services of a lower-level subsystem typically referred to as
a {\bf window system}\index{window system}. CLUE, in turn, forms the basis for a
more comprehensive {\bf user interface management system}
\index{user interface management system}\index{UIMS}
(UIMS).

CLUE depends on a window system to provide programmer interfaces for controlling
interactive I/O hardware  --- the display screen(s), the keyboard, the
pointer, etc.  Specifically, CLUE is defined in
terms of the X Window System protocol\cite{x-protocol} and CLX\index{CLX}, the
Common Lisp programmer's interface to the X Window System\cite{clx}. 

Most window systems, including X, contain a component that is commonly called the 
{\bf window manager}\index{window manager}. The window manager is the
part of the window system that provides a user interface to various operations on
windows --- changing a window's position, size, visibility, etc.
Since an X window manager is simply another application program (albeit a rather
specialized one), the
definition of a window manager is {\em not} included in the CLUE specification.

CLUE distinguishes two different aspects of programming the user
interface:

\begin{itemize}
\item Defining a contact
\item Using a contact
\end{itemize} 
The {\bf application programmer}\index{application programmer} who
instantiates and uses a contact object does not need to know 
how the class and methods of the contact were implemented 
by the 
{\bf contact programmer}\index{contact programmer}. 
In particular, the
window system interfaces used by the contact programmer need not be
visible to the CLUE application programmer. 

This distinction contributes to the separation of application
programming
from user interface programming, one of the primary goals of a
UIMS.
In terms of the Seeheim UIMS model\cite{pfaff-uims}, contacts represent
the presentation (or lexical) component of a user interface.
\index{user interface, lexical component}
\index{UIMS, presentation component}

\HIGHER{Summary of Features}
\LOWER{Contacts, Composites, and Interactive Streams}
CLUE defines the basic class of  {\bf contact} objects, the fundamental
components of a user interface. \index{contact}
Contacts are a subclass of the CLX {\tt xlib:window}\index{window} data type and a 
contact object may be used wherever a {\tt xlib:window} object is allowed. 

Additionally, CLUE defines the 
subclass of {\bf composites}, representing contacts which are the
``parents'' of other
contacts. A composite contact may be the parent of another composite,
leading to a tree-structured contact hierarchy. \index{composite}
A composite also furnishes geometry management and input focus management
services for the contacts which are its children.
{\bf Roots}\index{root} are special composite contacts used
to represent entire display screens. {\bf Shells}\index{shell} are composites
which handle the duties required by standard conventions for top-level
X windows\cite{icccm}\index{interclient communication}. CLUE defines several
shell subclasses which implement
client interaction with window managers and session managers.

An {\bf interactive 
stream} is another contact subclass defined by CLUE. Interactive streams
are designed to integrate CLUE with the conventional stream-based I/O of
Common Lisp.\index{interactive-stream}

\SAME{The Event Loop, Contact Displays, and Contact Input}
\index{contact-display}
CLUE defines the {\tt contact-display} object type, which represents the
basic input processing of an interactive application and which supports
the {\bf event loop model}\index{event loop model} for application
input. 
A {\tt contact-display} object inherits the behavior of a CLX
{\tt xlib:display} object\index{display} and can be substituted wherever a {\tt
xlib:display} is allowed.

In CLUE, the event loop is represented as an operation on a {\tt
contact-display} object, which dispatches input events to the
appropriate contact. At the center of the CLUE event loop,
the contact receiving an input event is then responsible for invoking all
appropriate responses.

\SAME{Graphics Contexts}
Clients of the X Window System
specify the visual attributes of graphical output primitives by using
{\bf graphics contexts}.
CLUE provides support for more efficient sharing of graphics context
objects among several components of the user interface.  Contact
programmers are still free to adopt various policies for sharing
graphics contexts, including hierarchical inheritance or no sharing at
all.

\SAME{Resources}
CLUE allows various values of
the
user interface (e.g.\ colors, fonts, title strings, etc.) to be treated as {\bf
resources} which can be stored and retrieved from  a {\bf resource
database}\index{resource, database}, using the resource management facilities of
CLX.  User interface values in a resource database can be modified
by a user ``externally,'' without change to the application program.
This provides a consistent mechanism for
contact objects to integrate the preferences of both the interface
programmer and an individual user.


\HIGHER{Previous Work}
The design of CLUE was modelled on the 
X-Toolkit (Xt) library
\index{X-Toolkit}\cite{Xt}.
The X-Toolkit is a user interface programming package, designed chiefly for
programmers using the C language, and distributed with the X Window
System itself.  CLUE could be described as a translation of the X-Toolkit
``intrinsics'' into the domain of Common Lisp and CLOS.


\SAME{Packages}
\index{CLUE package}\index{packages, CLUE}
All CLUE symbols (classes, functions, methods, macros, etc.) are interned in 
the package named {\tt CLUE}. Unless otherwise specified, all symbols defined by 
this specification are assumed to be interned in the {\tt CLUE} package.

\index{XLIB package}\index{packages, XLIB}
All symbols which belong to CLX are interned in the {\tt XLIB} package.
References in this document to CLX symbols will always specify the {\tt XLIB}
package explicitly.





\CHAPTER{Contacts}
\index{contact} 

\LOWERL{Using Contacts}{ch:contacts}
The fundamental properties of a contact are defined by the {\tt contact} class.
All contact classes must be defined using the {\tt
defcontact} macro (see Section~\ref{ch:defcontact}).
Contacts are a subclass of the CLX {\tt xlib:window}\index{window} data type and a {\tt
contact}
object may be used wherever a {\tt xlib:window} object is allowed. Because {\tt
xlib:window} is a subtype of {\tt xlib:drawable}, a {\tt contact} can also be an
argument to all CLX operations on {\tt xlib:drawable} objects.
\index{drawable}

{\large {\bf contact \hfill Class}} 
\index{classes, contact}
\begin{flushright}
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defcontact & contact & (xlib:window) \\
&\\
;; Hierarchy \\
&\\
  ((display &            :type xlib:display \\
&                        :reader & contact-display \\
&                        :initarg &  :display) \\
   (name &               :type & symbol \\
&                        :reader &  contact-name \\
&                        :initarg &  :name ) \\
   (parent &             :type & contact \\
&                        :accessor &  contact-parent \\
&                        :initarg &  :parent)\\
&\\
;; State \\
&\\
   (state &          :type & (member :withdrawn :managed :mapped)\\
&                        :accessor & contact-state \\
&                        :initarg &  :state \\
&                        :initform & :mapped) 
\end{tabular}}

\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
&\\
;; Callbacks \\
&\\
   (callbacks &          :type & list \\
&                        :reader &  contact-callbacks \\
&                        :initform &  nil) \\
&\\
;; Input control\\
&\\  
   (compress-exposures & :type & (member :off :on) \\
&                        :reader &  contact-compress-exposures \\
&                        :initform &  :off \\
&                        :allocation &  :class) \\
   (compress-motion &    :type & (member :off :on) \\
&                        :reader & contact-compress-motion \\
&                        :initform & :on \\
&                        :allocation & :class) \\ 
   (event-translations & :type & list \\
&                        :initform & nil) \\ 
   (event-mask &         :type & (or null xlib:event-mask) \\
&                        :accessor & contact-event-mask \\
&                        :initform & (xlib:make-event-mask :exposure)) \\
   (sensitive &          :type & (member :off :on) \\
&                        :accessor & contact-sensitive \\
&                        :initform & :on) \\
&\\
;; Attributes \\
&\\
   (border-width &       :type & xlib:card16 \\
&                        :reader & contact-border-width \\
&                        :initform & 1) \\
   (background & :type & (or (member :none :parent-relative) \\
                       &       & xlib:pixel xlib:pixmap)) \\
&                        :accessor & contact-background \\
&                        :initform & :parent-relative) \\
   (depth &              :type & xlib:card16 \\
&                        :reader & contact-depth \\
&                        :initform & 0) \\
   (height &             :type & xlib:card16 \\
&                        :reader & contact-height \\
&                        :initform & 0) \\
   (width &              :type & xlib:card16 \\
&                        :reader & contact-width \\
&                        :initform & 0) \\
   (x &                  :type & xlib:int16 \\
&                        :reader & contact-x \\
&                        :initform & 0) \\
   (y &                  :type & xlib:int16 \\
&                        :reader & contact-y \\
&                        :initform & 0)  
\end{tabular}}

\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
&\\
;; Internal\footnotemark \\
&\\
   initialization) \\
&\\
(:resources & \\
& \\
;; Slot values \\
& \\
 border-width       \\
 callbacks \\
 background \\ 
 depth \\
 event-mask \\
 event-translations \\
 height \\
 name \\
 sensitive \\
 width \\
 x \\
 y \\
&\\
;; Window attributes \\
&\\
 (backing-store &      :type & (or null (member :not-useful :when-mapped
:always))) \\
  (border &             :type & (or null (member :copy) xlib:pixel pixmap)) \\
  (cursor &             :type & (or null (member :none) xlib:cursor)) \\
  (override-redirect &  :type & (or null (member :on :off))) \\
  (save-under &         :type & (or null (member :on :off))) \\
&\\
;; Other resources \\
&\\
  (documentation &      :type & (or list string)) \\
  (screen &             :type & xlib:card8)))
\end{tabular}
}
\footnotetext{Internal slots  are
implementation-dependent and are not guaranteed to exist in every environment.
Programs which
use such slots may not be portable to every CLUE implementation.}

\end{flushright}


The slots of the {\tt contact} class are described below.

\begin{flushright} \parbox[t]{6.125in}{
{\tt display}
\begin{quote}
This slot is the same as the {\tt display} slot of an {\tt xlib:window} object.
A {\tt contact} is
always associated with a {\tt contact-display} object.
\index{contact-display}
See Section~\ref{ch:contact-display} for a
description of {\tt contact-display} objects.\end{quote}

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
{\tt name}
\begin{quote}
The name of the contact. Technically, this is
a resource name symbol which can be used to access contact resources
stored in a resource database. See Chapter~\ref{ch:resource-management}
for a complete discussion of contact resource management. 
\index{resource, name}
By default, the name of a contact is {\tt (class-name (class-of contact))}.
\end{quote}

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
{\tt parent}
\begin{quote}
The  parent contact of the contact (see Chapter~\ref{ch:contact-hierarchy}). 
CLUE automatically ensures that this slot value is always consistent with the
window hierarchy stored by the X server.
\index{X Window System, server}
The {\tt :parent} initarg is a required argument to the {\tt make-contact}
function.
\index{make-contact function}
\end{quote}

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
{\tt state}
\begin{quote}
A state variable which controls the visual effect of the contact. See
Section~\ref{ch:contact-state}. The state
of a contact determines whether it is viewable and whether it is under geometry
management control.
\end{quote}

}\end{flushright}


\begin{flushright} \parbox[t]{6.125in}{
{\tt callbacks}
\begin{quote}
{\tt callbacks} is an association list containing the contact
{\bf callbacks}.\index{callback}
Callbacks are also discussed in
Section~\ref{ch:callbacks}. 
\end{quote}

}\end{flushright}


\begin{flushright} \parbox[t]{6.125in}{
{\tt compress-exposures}, {\tt compress-motion}
\begin{quote}
Flags which control the filtering of redundant input events. See
Section~\ref{ch:compression}. 
These are class data shared by all instances of the contact class.
\index{input, compression} \end{quote}

}\end{flushright}



\begin{flushright} \parbox[t]{6.125in}{
{\tt event-translations}
\begin{quote}
{\tt event-translations} is lookup table which controls how the contact
responds to input events that it receives. Each of its elements
is an {\bf event translation}\index{event translation} which associates
an input event with one or more contact {\bf actions}\index{actions}. The
{\tt event-translations} are a contact resource that can be read from a
resource database. \index{resource, database}
See Section~\ref{ch:event-translation} for
a description of event translations and their syntax. 
\end{quote}

}\end{flushright}


\begin{flushright} \parbox[t]{6.125in}{
{\tt sensitive}
\begin{quote}
A flag which represents the contact's input sensitivity state. See
Section~\ref{ch:sensitive}. \end{quote}

}\end{flushright}



\begin{flushright} \parbox[t]{6.125in}{
{\tt x}, {\tt y}, {\tt width}, {\tt height}, {\tt border-width}
\begin{quote}
These geometrical attributes of a contact window are defined by CLX. Such
attributes can always be requested from the X server, but they are also made
available to the client application as slot values of the {\tt contact}
object. CLUE automatically ensures that these slot values are consistent with
the values stored by the X server.
\end{quote}

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
{\tt depth}, {\tt background}, {\tt event-mask}
\begin{quote}
These non-geometrical attributes of a contact window are defined by CLX. Such
attributes can always be requested from the X server, but they are also made
available to the client application as slot values of the {\tt contact}
object. CLUE automatically ensures that these slot values are consistent with
the values stored by the X server.\index{X Window System, server}
\end{quote}

}\end{flushright}


\LOWERL{Contact Creation}{ch:creation}

The creation of a contact object is actually a two-step process, in which a
contact instance is first {\bf initialized}\index{contact, initializing} and 
then {\bf realized}\index{contact, realizing}\index{realized}. Initialization consists
of collecting initial values for all contact attributes. However, no X server
\index{X Window System, server} resources (windows, etc.) are actually
allocated.  Later, when the contact is realized,
these resources are allocated and contact creation is complete. Postponing
server resource allocation until realization can make the process of creating a
new contact much more efficient. It is common for server resources to be
affected by operations that occur after initialization but before the contact is
actually displayed to the user. For example, when creating a complex contact
hierarchy, the addition of descendants can modify the size of ancestor contact
windows (see Chapter~\ref{ch:contact-hierarchy} for a discussion of composite
contacts and geometry management). In this case, realization of the composite
contact would occur after the initialization of all of its descendants and would
allocate a window using the final adjusted size.

Initialization of a new
contact object is performed by the {\tt
make-contact} function.
\index{make-contact function} 
Many initial attributes of a contact are considered to be
resources\index{resource} that can be read from a resource database
(see Chapter~\ref{ch:resource-management}).
Contact resources are described in the resource specification list given in the
{\tt defcontact} form defining a contact class (see
Section~\ref{ch:defcontact}).  \index{defcontact macro}
For example, the resource specification list for the {\tt contact} class allows values for
certain slots, for window creation attributes, and for other
attributes to be read from a resource database during contact
initialization.
The {\tt make-contact} function implements most of the resource processing done during
contact initialization\footnotemark\footnotetext{Implementation Note: It
is also possible to create a new metaclass for contact objects, with a
specialized {\tt default-initargs} method for getting
initializations from a resource database. This would mean that
the CLOS {\tt make-instance} function could be used instead of
{\tt make-contact}. However, standardization of CLOS metaclass
functionality is currently incomplete. Furthermore, the use of a special
{\tt make-contact} function allows for various optimizations in
contact initialization.}. 

Typically, CLUE programmers need not be aware of contact realization.  CLUE
realizes a contact automatically by calling the {\tt realize}
function\index{realize method} during the next call to {\tt
process-next-event}\index{process-next-event function} after initialization.
However, there are cases when it is useful to invoke the {\tt
update-state}\index{update-state function} function to cause realization
explicitly (see Section~\ref{ch:contact-state}).  Contact programmers can use
the {\tt realized-p} method\index{realized-p method} to ensure that operations
which depend on the existence of contact server resources are not performed
before the contact has been realized.  For example, graphics output to a contact
cannot occur before it is realized, because its window does not yet exist.

{\large {\bf make-contact \hfill Function, contact}}
\index{contact, make-contact function}
\index{make-contact function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & make-contact & \\
& (class\\
& \&rest & initargs\\
& \&key & parent\\
&       & defaults))
\end{tabular}
\rm

}\end{flushright}


\begin{flushright}
\parbox[t]{6.125in}{
Creates and returns a new
instance of the given contact {\tt class}, according to the remaining
{\tt initargs}, 
which are keyword-value pairs. The optional {\tt :defaults} argument is a list
of keyword-value pairs; its use is described later below.}

\parbox[t]{6.125in}{
A value for the {\tt :parent} argument must be
given. The parent may be a {\tt contact} or a {\tt contact-display} object.
If a  {\tt contact} is given as the parent, then the new contact is associated
with the parent's {\tt contact-display}. If a {\tt
contact-display}  is given as the parent, then the new contact is associated
with the {\tt contact-display} and its parent is set to the {\tt root} 
given by the value of the contact's {\tt screen} resource or (if no such
resource value has been defined) to the default root of the {\tt
contact-display}.
\index{root, default}\index{contact-display, default root}}

\parbox[t]{6.125in}{
In addition to slot-filling initargs, keyword arguments may be contact resource
names. Resource values given as arguments to {\tt make-contact} override
those read from a resource database.\index{resource, database}

}

\parbox[t]{6.125in}{
The {\tt make-contact} function also establishes an initial value for each of the
contact's resources (see Section~\ref{ch:contact-class-resources}). 
\index{contact, resource initialization}
\index{resource, initialization}
Class resources for the contact are determined by the
contact class and are specified when the contact class is defined, using the
{\tt defcontact} macro\index{defcontact macro}
(see Section~\ref{ch:defcontact}). Constraint resources for the contact
are determined by the class of the contact's parent.\index{resource, constraint} 
For each contact resource 
a value is determined by the following procedure.

\begin{itemize}
\item If the resource name keyword appears in {\tt initargs} with a
non-{\tt
nil} value, then the value given is used (specifying a {\tt nil} resource value
in {\tt initargs} is equivalent to omitting the resource name altogether).

\item If no value was found in the previous step, then  the complete resource
name and
class are used to look up a value in a resource database
\index{resource, database} (see Section~\ref{ch:accessing-resources}). 
The resource database used is given by the value of the special variable {\tt
*database*}.\index{*database*}\index{variables, *database*}

\item If no value was found in the previous step and the resource name
appears in the {\tt :defaults} list  with a non-{\tt nil} value, then
this value is used. Thus, assigning a resource value in the {\tt
:defaults} list is a
way for an application programmer to suggest a resource value which may be
overridden by the contents of the resource database.

\item If no value was found in the previous step, then the value used is the one
specified for the default resource value in the {\tt defcontact} form defining
the contact class (i.e. the value of the resource
specification\index{resource, specification} {\tt :initform} option).

\item If the resource  is a contact slot name and if no
value was found by the previous steps, then the {\tt :initform} value for
the slot is used.
\end{itemize}
} 

\parbox[t]{6.125in}{
If the resource name is a contact slot name, then the slot is set to the
value found. If the contact programmer is also using non-slot resources, then an
{\tt initialize-instance :after} method must be defined to handle these values.
\index{resource, non-slot}
}


\parbox[t]{6.125in}{ If the initial value found for a resource is not of the
type given by the {\tt :type} option in its resource specification,
then
{\tt make-contact} will attempt to convert the value to the correct type.  The
new contact's {\tt convert} method is called to perform all representation type
conversions for resources (see
Section~\ref{ch:representation-types}).\index{convert method} 
This type
conversion is a convenient way to initialize a slot or resource with an object
which must created by a request to the X server (e.g.  {\tt xlib:font}, {\tt
xlib:cursor}, {\tt xlib:pixmap}, etc.).

}\end{flushright}



\SAMEL{Contact State}{ch:contact-state}
\index{contact, state}
The visual effect of a contact upon the user interface is controlled by the
value of its {\tt state} slot and is related to two
factors\footnotemark\footnotetext{See Chapter~\ref{ch:contact-hierarchy} for a complete discussion of contact
hierarchy and geometry management.
}.
\begin{itemize}

\item {\bf Mapping}:
The concepts of {\bf mapped}\index{mapped}, {\bf viewable}\index{viewable}, and
{\bf visible}\index{visible} apply to any {\tt xlib:window} object and therefore
to contacts as well\cite{x-protocol}.
A contact is said to be ``mapped'' if {\tt (xlib:map-window
contact)} has been called. A contact is ``viewable'' if it and all of its
ancestors are mapped. A contact is ``visible'' only if someone looking at the
display screen can actually see some part of it; that is, the contact is
viewable and is not completely occluded by any other windows.
\index{contact, mapped}
\index{contact, visible}
\index{contact, viewable}

\item {\bf Geometry management}: A contact under geometry management control is
\index{geometry management}\index{managed}\index{contact, managed}
said to be ``managed.'' As a
result of CLUE geometry management, any changes to the position or size of a
managed contact may affect the geometry of its managed siblings, its parent, and
(in general) any other managed member of the contact subtree to which it
belongs.  Creating or destroying a managed contact can have a similar
result. However, changes involving an unmanaged contact
do not have this kind of ``ripple'' effect on the visible user interface. 
\end{itemize}

These factors are not independent. In CLUE, it is invalid for a contact
to be mapped but unmanaged, because this contradicts the purpose of geometry
management\footnotemark\footnotetext{However, CLUE does not prevent a
programmer who truly wants a mapped-but-unmanaged contact from using
{\tt xlib:map-window} to accomplish this.}. Thus, the {\tt state} slot of a
contact has one of three values.

\begin{center}
\begin{tabular}{ll}
{\tt :withdrawn} & The contact is unmanaged and unmapped.\\
 {\tt :managed} & The contact is managed but unmapped.\\
 {\tt :mapped} & The contact is both  managed and mapped.
\end{tabular}
\end{center}


The conditions corresponding to a contact's {\tt state} are not guaranteed to be
satisfied until the contact is realized.
\index{contact, realizing}\index{realized}
CLUE calls the {\tt update-state} function 
\index{update-state function} in
order to force consistency of the state of all contacts belonging to a {\tt
contact-display} (see Section~\ref{ch:contact-display}).
\index{contact-display}

{\samepage
{\large {\bf update-state \hfill Function, contact-display}} 
\index{update-state function}
\index{contact-display, update-state function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & update-state & \\ 
& (contact-display))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Makes the user interface consistent with the current {\tt state} of the contacts
belonging to the {\tt contact-display}. Any unrealized contact is realized; if
it is also managed, then geometry management is invoked to negotiate its initial
position, size, and priority. Any {\tt :mapped} contact is mapped.

{\tt update-state} is called internally by CLUE (by  {\tt process-next-event})
\index{process-next-event function} and is not typically called by CLUE
programmers directly. However,
there are cases when it is useful to invoke the {\tt update-state} function to
cause
realization explicitly (for example, to complete initial negotiation of the size
of a {\tt :managed} contact before positioning and mapping it). 

}\end{flushright}

The default {\tt state} value is {\tt :mapped}. As a result, unless
specified otherwise, all contacts will automatically be viewable after 
{\tt update-state} is called (in particular, after a call to {\tt
process-next-event}).  After initialization and realization, 
the {\tt (setf contact-state)} accessor method causes transitions in a contact's
state and its visible effect. The most common usages are setting a contact's
state to {\tt :withdrawn} to withdraw it or to {\tt :mapped} to present it.
\index{contact, presented}\index{contact, withdrawn}

\SAMEL{Application Programmer Interface}{ch:api}
\index{contact, application programmer interface}
The following are the basic functions  used by
application programmers to operate on contacts. Some of these are generic
functions for which the {\tt contact} class defines a method.

{\samepage
{\large {\bf (setf contact-state) \hfill Method, contact}}
\index{contact, contact-state method}
\index{contact-state method}
\begin{flushright}
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf contact-state) & \\
& (new-state \\
&  (contact  contact)))
\end{tabular}
\rm
}\end{flushright}}

\begin{flushright}
\parbox[t]{6.125in}{
\index{contact, presented}\index{contact, withdrawn}
\index{contact, state}
Changes the state of the {\tt contact} to the {\tt new-state}. The visible effect
of contact state transitions are described below.

\begin{center}
\begin{tabular}{lp{4.25in}}
New Value & Visible Effect \\ \hline \\
{\tt :withdrawn} & The contact is withdrawn, i.e. removed from geometry management and
made invisible and unavailable for input.\\ 
\\
{\tt :mapped} & The contact is presented, i.e. mapped and placed under geometry
management.\\ \\
{\tt :managed} &  The contact is unmapped and placed under geometry management. 
\end{tabular}
\end{center}

See Section~\ref{ch:geometry-management} for a complete discussion of 
geometry management.

}\end{flushright}


{\samepage
{\large {\bf change-geometry \hfill Function, contact}}
\index{contact, change-geometry function}
\index{change-geometry function}
\begin{flushright}
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & change-geometry & \\
& (contact\\
& \&key & x  \\
& & y   \\
& & width \\
& & height   \\
& &border-width\\
& &accept-p) \\
(declare &(values &approved-p x y \\
&& width height border-width)))
\end{tabular}
\rm}
\end{flushright}
}

\begin{flushright}\parbox[t]{6.125in}{
Requests a change to one or more components of the contact's geometry.
Approval of the request is handled by the contact's parent (see
Section~\ref{ch:geometry-management}).
The return values indicate how the parent handled the 
request. If {\tt approved-p} is non-{\tt nil}, then the request was performed as
requested and
the resulting new geometry values are returned.  Otherwise, the request was not
performed, but the geometry
values returned suggest a compromise request which can be approved instead.
If only {\tt nil} is returned, no geometry change is allowed.
}\end{flushright}

\begin{flushright}\parbox[t]{6.125in}{
If {\tt accept-p} is non-{\tt nil}, then any compromise geometry suggested will be
accepted and performed immediately. Non-{\tt nil} is returned for {\tt
approved-p} if the original request was performed; if a compromise request was
performed instead, then {\tt nil} is returned.
}\end{flushright}

\begin{flushright}\parbox[t]{6.125in}{ 
A special case occurs when the {\tt contact} is a top-level {\tt
shell}.\index{shell}\index{contact, top-level} In this case, geometry management
is provided by the window manager,\index{window manager} and requested geometry
changes (possibly modified by the window manager) are performed immediately.
Thus, when the {\tt contact} is a top-level {\tt shell}, {\tt change-geometry}
{\em always} behaves as if {\tt accept-p} is true.
}\end{flushright}



{\samepage
{\large {\bf change-priority \hfill Function, contact}}
\index{contact, change-priority function}
\index{change-priority function}
\begin{flushright}
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & change-priority & \\
& (contact\\
&  priority & ;(member :above :below :top-if :bottom-if :opposite)\\
& \&key & sibling\\
& & accept-p) \\
(declare &(values &approved-p priority sibling)))
\end{tabular}
\rm}
\end{flushright}}

\begin{flushright}\parbox[t]{6.125in}{
Requests a change to the contact's stacking priority.
See the CLX function {\tt xlib:window-priority} for a description of the {\tt
priority} and {\tt sibling} arguments.
Approval of the request is handled by the contact's parent (see
Section~\ref{ch:geometry-management}).
The return values indicate how the parent handled the 
request. If {\tt approved-p} is non-{\tt nil}, then the request was performed as
requested and
the resulting new priority values are returned.  Otherwise, the request was not
performed, but the priority
values returned suggest a compromise request which can be approved instead.
If only {\tt nil} is returned, no priority change is allowed.
}\end{flushright}

\begin{flushright}\parbox[t]{6.125in}{
If {\tt accept-p} is non-{\tt nil}, then any compromise request suggested will be
accepted and performed immediately. Non-{\tt nil} is returned for {\tt
approved-p} if the original request was performed; if a compromise request was
performed instead, then {\tt nil} is returned.
}\end{flushright}

\begin{flushright}\parbox[t]{6.125in}{ 
A special case occurs when the {\tt contact} is a top-level {\tt
shell}.\index{shell}\index{contact, top-level} In this case, geometry management
is provided by the window manager,\index{window manager} and the requested
priority
change (possibly modified by the window manager) is performed immediately.
Thus, when the {\tt contact} is a top-level {\tt shell}, {\tt change-priority}
{\em always} behaves as if {\tt accept-p} is true.
}\end{flushright}


{\samepage
{\large {\bf destroy \hfill Method, contact}}
\index{contact, destroy method}
\index{destroy method}
\begin{flushright}
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & destroy & \\
& ((contact  &contact)))
\end{tabular}
\rm
}\end{flushright}

\begin{flushright}\parbox[t]{6.125in}{
Called only when the contact will no longer be referenced. Frees any
resources used by the contact. In particular, its window will be destroyed.
The primary {\tt contact} method for {\tt destroy} invokes the contact's
{\tt :destroy} callback (see Section~\ref{ch:callbacks}).
\index{contact, :destroy callback}
}\end{flushright} }


\SAMEL{Contact Programmer Interface}{ch:contact-cp-interface}\index{contact, contact programmer interface}
The following functions are
not intended to be called directly
from application programs. However, a contact programmer will  use them to
define the basic behavior of a new contact
class.  
Several functions in this contact programmer interface are generic functions for
which the {\tt
contact} class defines methods; these methods may be redefined or modified by the
contact programmer. In general, there are three types of functions  which
are used primarily by contact programmers.

\begin{center}
\parbox[t]{1in}{{\bf Characteristic}} \hspace{.125in} \parbox[t]{4in}{Have
methods that are typically redefined for each contact class.} 

\parbox[t]{1in}{{\bf Management}} \hspace{.125in} \parbox[t]{4in}{Have methods
used
internally to perform various management operations. These methods  may have
{\tt :before}, {\tt :after}, or {\tt :around} methods for different classes.} 

\parbox[t]{1in}{{\bf Inquiry}} \hspace{.125in} \parbox[t]{4in}{Return
information used to implement contact methods.} 
\end{center}

{\samepage
\subsection*{Characteristic Functions}\index{contact, characteristic functions}

{\large {\bf display \hfill Method, contact}}
\index{contact, display method}
\index{display method}
\begin{flushright}
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & display & \\
& ((contact  &contact)\\
& \&optional & x\\
& & y\\
& & width \\
& & height\\
& \&key))
\end{tabular}}\end{flushright}
}

\begin{flushright}
\parbox[t]{6.125in}{
Displays the contact. The  {\tt x}, {\tt y}, {\tt width}, and
{\tt height} parameters indicate  the  rectangular
portion of the contact which needs to be (re)displayed. {\tt x} and {\tt y}
are given relative to the contact's  origin. If no optional parameters are
given, this method should display the entire contact.

This method is called  during contact input processing, in
response to Expose events.
If the {\tt compress-exposures} slot of a contact's class is {\tt :on},
then {\tt display} will be called only for Expose events in which the expose
count is zero.
\index{input, compression}\index{event, compression}
See Section~\ref{ch:compression} for a description of event compression.

The lambda list for this generic function includes {\tt \&key} so that contact
programmers can define methods with additional keyword arguments.
}\end{flushright}


{\samepage
{\large {\bf accept-focus-p \hfill Method, contact}}
\index{contact, accept-focus-p method}
\index{accept-focus-p method}
\begin{flushright}
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & accept-focus-p & \\
& ((contact  &contact)) \\
(declare & (values & boolean)))
\end{tabular}
\rm}
\end{flushright}
}

\begin{flushright}\parbox[t]{6.125in}{\index{input, focus}
Returns  non-{\tt nil} if and only if the contact is willing to become the
keyboard input focus. A contact which does not respond to keyboard input
events should always return {\tt nil} as the value of this method. The
primary method for the {\tt contact} class determines the value returned by
inspecting the contact's {\tt event-mask}.  Management of
contact input focus is discussed further in Section~\ref{ch:focus-management}.

}\end{flushright}

{\samepage
{\large {\bf preferred-size \hfill Method, contact}}
\index{contact, preferred-size method}
\index{preferred-size method}
\begin{flushright}
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & preferred-size & \\
& ((contact  &contact)\\
& \&key\\
&  width \\
&  height\\
&  border-width) \\
(declare & (values & width height border-width)))
\end{tabular}
\rm}
\end{flushright}
}

\begin{flushright}\parbox[t]{6.125in}{
Returns the preferred size of the {\tt contact}, based on its current state
plus the changes suggested by the {\tt width}, {\tt height}, and {\tt
border-width} arguments. This allows the {\tt contact} to suggest to its geometry
manager a size that best fits its current contents, taking into account
certain changes that the geometry manager anticipates making. However, a
geometry manager
is free to ignore or override this preferred size (see Section~\ref{ch:geometry-management}).}
\end{flushright}

\begin{flushright}\parbox[t]{6.125in}{
The primary method for {\tt preferred-size} is compliant, returning the
given keyword value (or, if no keyword is given, the current value) for {\tt width},
{\tt height}, and {\tt border-width}.}\end{flushright}

{\samepage
\subsection*{Management Functions}\index{contact, management functions}
{\large {\bf initialize-instance \hfill Method, contact}}
\index{contact, initialize-instance method}
\index{initialize-instance method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & initialize-instance & \\
& ((contact  contact)\\
& \&key \\
& \&allow-other-keys))
\end{tabular}
\rm

}\end{flushright}
}

\begin{flushright} \parbox[t]{6.125in}{
See Section~\ref{ch:creation}. The contact programmer must define an
{\tt initialize-instance :after} method to  
handle initialization for any non-slot resources.
\index{resource, initialization}\index{resource, non-slot}
 
}\end{flushright}



{\large {\bf realize \hfill Method, contact}}
\index{contact, realize method}
\index{realize method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & realize & \\
& ((contact  &contact)))
\end{tabular}
\rm

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Realizes the {\tt contact}.
\index{contact, realizing}
}\end{flushright}


{\large {\bf move \hfill Method, contact}}
\index{contact, move method}
\index{move method}
\begin{flushright}
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & move & \\
& ((contact  &contact)\\
& x & \\
& y))
\end{tabular}
\rm

Called in order to actually change the position of the contact.
An application program must first call {\tt change-geometry} 
\index{change-geometry function}
in
order to invoke geometry management. The {\tt move} method is called only by {\tt change-geometry}.
The contact programmer, however, may find it useful to attach auxiliary methods to {\tt
move}.

}\end{flushright}

{\samepage
{\large {\bf resize \hfill Method, contact}}
\index{contact, resize method}
\index{resize method}
\begin{flushright}
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & resize & \\
& ((contact  &contact)\\
& width & \\
& height   \\
&border-width))
\end{tabular}
\rm
}\end{flushright}
}

\begin{flushright} \parbox[t]{6.125in}{
Called in order to actually change the size of the contact.
An application program must first call {\tt change-geometry} 
\index{change-geometry function}
in
order to invoke geometry management. The {\tt resize} method is  called
only by {\tt change-geometry}.
The contact programmer, however, may find it useful to attach auxiliary methods to {\tt
resize}.


}\end{flushright}

\subsection*{Inquiry Functions}\index{contact, inquiry functions}

{\samepage
{\large {\bf contact-complete-class \hfill Function, contact}}
\index{contact, contact-complete-class function}
\index{contact-complete-class function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & contact-complete-class & \\
& (contact) \\
(declare & (values & complete-class-list)))
\end{tabular}
\rm
}\end{flushright}
}

\begin{flushright} \parbox[t]{6.125in}{
Returns a list of symbols containing the {\bf complete resource class} of the contact.
\index{complete resource class}
\index{resource, complete class}
See Section~\ref{ch:complete-names}.

}\end{flushright}


{\samepage
{\large {\bf contact-complete-name \hfill Function, contact}}
\index{contact, contact-complete-name function}
\index{contact-complete-name function}
\begin{flushright}
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & contact-complete-name & \\
& (contact) \\
(declare & (values & complete-name-list)))
\end{tabular}
}\end{flushright}}

\begin{flushright}
\parbox[t]{6.125in}{
Returns a list of symbols containing the {\bf complete resource name} of the contact.
\index{complete resource name}
\index{resource, complete name}
See Section~\ref{ch:complete-names}.
}\end{flushright}


{\samepage
{\large {\bf destroyed-p \hfill Function, contact}} 
\index{destroyed-p function}
\index{contact, destroyed-p function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & destroyed-p & \\ 
& (contact) \\
(declare &(values  & boolean)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns non-{\tt nil} if the contact is being destroyed. Because output to the X
server is buffered, there can be a delay between the time that {\tt destroy} is
called and the time that all contact display resources have been freed.

}\end{flushright}



{\samepage
{\large {\bf inside-contact-p \hfill Method, contact}} 
\index{inside-contact-p method}
\index{contact, inside-contact-p method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & inside-contact-p & \\ 
& ((contact & contact)\\
&  x\\
&  y) \\
(declare &(values  & boolean)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns non-{\tt nil} if the given point  is
inside the {\tt contact}. {\tt x} and {\tt y} are relative to the origin of the
{\tt contact} coordinate system.

}\end{flushright}



{\samepage
{\large {\bf realized-p \hfill Method, contact}}

\index{contact, realized-p method}
\index{realized-p method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & realized-p & \\
& ((contact  &contact))\\
(declare &(values & boolean)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns non-{\tt nil} if and only if the contact has been realized.
\index{contact, realizing}
See Section~\ref{ch:creation}.

}\end{flushright}


{\samepage
{\large {\bf resource \hfill Function, contact}}
\index{contact, resource function}
\index{resource function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & resource & \\
& (contact\\
& resource-name) \\
(declare &(values &resource-value)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns the value found for a contact resource when the contact was initialized.
{\tt resource-name} is the name of a resource defined in the resource
specification list for the {\tt contact}'s class or one of its superclasses.
\index{resource, specification}
See Section~\ref{ch:accessing-resources}.

}\end{flushright}


{\samepage
{\large {\bf sensitive-p \hfill Function, contact}} 
\index{sensitive-p function}
\index{contact, sensitive-p function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & sensitive-p & \\ 
& (contact) \\
(declare &(values  & boolean)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns non-{\tt nil} if the contact is sensitive. 
A contact is sensitive if and
only if it and all of its ancestors have a value  of {\tt :on} for their {\tt
sensitive} slots.
See
Section~\ref{ch:sensitive} for a discussion of input sensitivity.
\index{input, sensitivity}

}\end{flushright}



\SAMEL{Callbacks}{ch:callbacks}

A {\bf callback}\index{callback} is a function which represents a connection
between a contact and the rest of an application program. A contact calls a
callback function in order to report the results of the user interface component
which it represents. Thus, callbacks have a crucial role in a CLUE application:
they provide a link between the application and its user interface. Callbacks
represent the application ``semantics'' of the user interface.
\index{user interface, semantic component}
Similarly, callbacks can be used by a contact to communicate its results to
another contact. This means that callbacks are also involved in the
implementation of the ``syntax'' that ties together the various components of a
user interface. \index{user interface, syntactic component}

Each {\tt contact} instance has a {\tt callbacks} slot containing a list of its
callback functions.  The {\tt callbacks} slot is an association list containing
elements of the form 
{\tt ({\em callback-name (function argument*)*})}.
That is, the {\tt callbacks} list associates a {\em callback-name} symbol with a
sequence of functions and their (optional) argument lists.  The {\em
callback-name} is used by the contact programmer to invoke each of the
associated functions with the given arguments.

Both the contact programmer and the application programmer are involved in
establishing a contact's callbacks.  The contact programmer defines a set of
callback names and, for each callback, the basic argument and return value
protocol to be used.  The contact programmer is also responsible for the
implementation of contact methods, in which callback functions are invoked via
the callback names.  The application programmer is responsible for associating
with each callback name the actual function(s) and arguments used to implement
it. The application programmer can also extend the basic argument protocol used
by associated functions.

The relationship between a callback name and an associated function resembles
that between a method name and the code which implements it.  In particular, the
set of callback names used is the same for all instances of a contact class.
These callback names and interfaces constitute a critical part of the
application programmer interface to a contact class.
\index{contact, application programmer interface}
However, the key difference is that the associated callback functions and
arguments are instance data that are usually different for each class instance.

For example, a contact programmer may define a slider contact which uses a
callback named {\tt user-changed\-value}.  The contact programmer arranges for
this callback to be invoked each time the user manipulates the slider position
and for it to be passed an argument indicating the new slider value.  A
programmer of a robot control application may use such a slider to
allow a user to adjust the rate at which the robot moves.  The application
programmer will thus want to modify the slider's {\tt callbacks} slot by adding
an element like {\tt (user-changed-value change-robot-speed)}. In this case,
{\tt change-robot-speed} should be an application function which accepts a
single argument specifying the new robot speed.

Callback functions are called using the {\tt apply-callback} macro.  The {\tt
callbacks} list of a contact can be modified by the functions {\tt add-callback}
and {\tt delete-callback}. Only one callback is involved in the basic
contact application programmer interface described in
Section~\ref{ch:api} --- the {\tt :destroy} callback, which is called by
the primary {\tt destroy} method.

{\samepage
{\large {\bf apply-callback \hfill Macro, contact}} 
\index{apply-callback macro}
\index{contact, apply-callback macro}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmacro & apply-callback & \\ 
& (contact\\
&  name\\
& \&rest arguments)\\
(declare &(values callback-values)))
\end{tabular}
\rm

}\end{flushright}
}

\begin{flushright} 
\parbox[t]{6.125in}{
Calls and returns the value(s) of the functions associated with the callback
{\tt name} in the
{\tt callbacks} list of the contact. Associated functions are called in order,
and the values returned are the values of the last function called. If no such
function exists, then {\tt nil} is returned.} 

\parbox[t]{6.125in}{
Callback functions are executed within a {\tt catch} form using the tag {\tt
:abort-callback}.  If a callback function executes {\tt (throw :abort-callback
{\em value*})}, then {\tt apply-callback} immediately returns the given {\em
value} arguments.
\index{callback, aborting}}

\parbox[t]{6.125in}{ The argument list passed to each associated callback
function consists of the given {\tt arguments}, followed by any function
arguments associated with the function in the {\tt callbacks} list.  Thus, the
caller of {\tt apply-callback} will not be aware of arguments taken from the
{\tt callbacks} list.  This allows an application programmer freedom to extend
the callback calling sequence defined by the contact programmer.  }

\parbox[t]{6.125in}{
Additionally, {\tt apply-callback} binds the special variable {\tt *contact*} to
\index{*contact*}\index{variables, *contact*}
the value of its {\tt contact} argument. {\tt *contact*} may then be used
within
the dynamic extent of {\tt apply-callback} to refer to the contact
invoking the callback.  
}
\end{flushright}

{\samepage
{\large {\bf callback-p \hfill Function, contact}} 
\index{callback-p function}
\index{contact, callback-p function}

\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & callback-p & \\ 
& (contact\\
&  name)\\
(declare &(values list)))
\end{tabular}
\rm

}\end{flushright}
}

\begin{flushright} 
\parbox[t]{6.125in}{
Returns the list of functions and argument lists associated with the callback
{\tt name} for the {\tt contact}. The return value is a list of the form 
{\tt ({\em (function argument*)*})}.
Returns {\tt nil} if no callback functions are associated with  the {\tt name}.}
\end{flushright}

{\samepage
{\large {\bf add-callback \hfill Function, contact}} 
\index{contact, add-callback function} 
\index{add-callback function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & add-callback & \\ 
& (contact\\
& name \\
& function\\
& \&rest & arguments)\\
(declare &(values &name)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Creates an entry in the {\tt callbacks} list of the {\tt contact} which
associates the given callback {\tt name} with the given {\tt function}
object and {\tt arguments}.
The {\tt function} and {\tt arguments} are placed at the end of the list of
callback functions associated with the callback {\tt name}.
The {\tt arguments} replace any previous arguments for the {\tt function} in the
{\tt callbacks} list.

}\end{flushright}

{\samepage
{\large {\bf delete-callback \hfill Function, contact}}
\index{contact, delete-callback function} 
\index{delete-callback function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & delete-callback & \\ 
& (contact\\
&  name \\
&  function))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Disassociates the callback {\tt function} from the given callback {\tt name} on
the contact's {\tt callbacks} list. 

}\end{flushright}


{\samepage
{\large {\bf *contact* \hfill Variable}} 
\index{*contact*}\index{variables, *contact*}


\begin{flushright} \parbox[t]{6.125in}{
Bound to the contact argument of {\tt apply-callback} in its dynamic
extent.

}\end{flushright}}

{\samepage
{\large {\bf :destroy \hfill Callback, contact}} 
\index{contact, :destroy callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & destroy-function & ())
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked by the primary {\tt contact} method for {\tt destroy}.
\index{contact, destroy method}
\index{destroy method}
Application programmers can define {\tt :destroy} callback functions to
perform special cleanup tasks or to enforce ``existence'' constraints
related to contacts.

}\end{flushright}



\HIGHERL{Defining a Contact Class}{ch:defcontact}
\index{defcontact}\index{contact, defining a class}
The {\tt defcontact} macro is used by a contact programmer to define a
new contact class.  Expansion of
this macro generates a {\tt defclass} form defining the class.  

{\samepage
{\large {\bf defcontact \hfill Macro}} 
\index{defcontact macro}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmacro & defcontact & \\ 
& (class-name\\
& superclasses\\
& slots\\
& \&rest & options))
\end{tabular}
\rm

}\end{flushright}
}

\begin{flushright} 
\parbox[t]{6.125in}{
Generates a {\tt defclass} form defining the {\tt
class-name} class, using the {\tt class-name}, {\tt superclasses}, {\tt
slots}, and {\tt options}.  
}

\parbox[t]{6.125in}{
{\tt class-name}
\begin{quote}
A class name symbol.   
\end{quote}
}
 
\parbox[t]{6.125in}{
{\tt superclasses}
\begin{quote}
A list of superclass symbols for use in a {\tt defclass} form. 
\end{quote}
}

\parbox[t]{6.125in}{
{\tt slots}
\begin{quote}
A list of slot specifications for use in a {\tt defclass} form. 
\end{quote}
}

\parbox[t]{6.125in}{
{\tt options}
}

\parbox[t]{5.75in}{
Each  remaining argument gives a class option for {\tt class-name}.
Each class option is a list of the form {\tt ({\em option-keyword
args*})}.  Valid class options are: 

\begin{center}
\begin{tabular}{lp{2.5in}}
{\tt (:constraints {\em resource-specification*})} & 
Defines the constraint resources used by the class. See
Section~\ref{ch:contact-class-resources}.\index{resource} \\ \\

{\tt (:documentation {\em string})} & 
Defines a documentation string associated with the class.\\ \\

{\tt (:resources {\em resource-specification*})} & 
Defines the resources used by the class. See
Section~\ref{ch:contact-class-resources}.\index{resource} \\
\end{tabular}
\end{center}
}
\end{flushright}

Resources and constraint resources for a contact class are defined by
{\bf resource specifications}. Each resource
specification \index{resource, specification}
is either a resource name symbol or a list of the following form.
\begin{quotation}
\tt
\begin{tabbing}
({\em resource-name} \= {\em [} :type {\em type-specifier} {\em ]}\\
\> {\em [} :class {\em resource-class} {\em ]}\\
\> {\em [} :initform {\em form} {\em ]} \\
\> {\em [} :documentation {\em string} {\em ]}\ )
\end{tabbing}
\end{quotation}


{\em resource-name} and {\em resource-class} are the resource name and class
symbols used to access a contact resource.  
\index{resource, name}\index{resource, class}
If {\tt :class} is not given, then
the {\em resource-name} is also used as the class name.
The {\tt :type} value is a type specifier which defines the representation type
used for the resource.\index{resource, representation type}
If the {\em resource-name} is also a slot name, then {\tt :type} option may
be omitted; in this case,
the slot {\tt :type} option is used as the resource representation type.
The {\tt :initform} option gives a form which may be evaluated to define the
initial resource value. The {\tt :documentation} option furnishes a
documentation string which describes this contact resource.

For programmer convenience, if the {\em resource-name} is also a slot name, then
a keyword initarg of the same name is automatically declared for the
slot.


Note that the {\tt :resources} option of {\tt defcontact} can play the
same role in contact initialization as the {\tt :default-initargs}
option of {\tt defclass} and that {\tt defcontact} therefore does not
accept {\tt :default-initargs} as a valid option.  Instead of {\tt
(:default-initargs name value)}, a programmer should specify {\tt
(:resources (name :initform value))}.




\CHAPTERL{Input}{ch:input}
\index{input}\index{contact-display}
CLUE defines the {\tt contact-display} object type, which represents the
basic input processing of an interactive application and which supports the {\bf
event loop model}\index{event loop model} for application input. (The
more specialized 
{\bf stream I/O model}\index{stream I/O model} provides a simpler application
interface to user interaction, based on {\bf interactive stream
contacts}.\index{interactive-stream} See
Chapter~\ref{ch:interactive-stream}.)\index{input, models}

\index{event loop model}
In the event loop model, an interactive application has the following generic
structure.\index{event loop}  
\begin{itemize}
\item Create and initialize the {\tt contact-display}.
\item Create and initialize contacts.
\item Read an input event and dispatch it to the appropriate contact. 
\item Repeat the previous step (the event loop) until the application terminates.
\end{itemize}

In CLUE, the event loop is represented as an operation on a {\tt
contact-display} object. Section~\ref{ch:event-loop} discusses the CLUE function
which implements the application event loop.

CLUE input processing is based on {\bf action}\index{actions} methods.
CLUE defines  operations which
associate input events with actions and  process events by
calling the appropriate action functions.
The process of finding the appropriate contact and its actions is
referred to as ``dispatching'' the event.
\index{event, dispatching}
All responses of a CLUE user
interface to input events occur as ``side-effects'' of actions. 


At the center of the CLUE event loop,
the contact receiving an input event is then responsible for invoking all
appropriate responses. A contact's
response to an input event may be one or more of the following.
\begin{itemize}
\item Provide input echoing or feedback, without application intervention
(lexical processing).\index{user interface, lexical component}
\item Inform another  user interface component of the
event (syntactic processing).\index{user interface, syntactic component}
\item Invoke application functions
(semantic processing).\index{user interface, semantic component}
\end{itemize}
 
For any contact receiving an input event, its response to the event involves a
process of {\bf event translation}.\index{event, translation}
Each contact can maintain a set of mappings which translates  specific events
into sequences of actions. Since
these
mappings can be read from a resource database\index{resource, database}
as contact resources, a user can tailor a contact's input responses to suit his
preferences. Event translation and other aspects of contact input programming are
described in Section~\ref{ch:contact-input-programming}.

\LOWERL{The Contact Display}{ch:contact-display}
The {\tt contact-display} object type defines the fundamental mechanisms for
associating
a contact  with a CLX {\tt xlib:display}\index{display} object and for dispatching
interactive input events to the contacts which will process them.


A {\tt contact-display} object inherits the behavior of a CLX {\tt
display} object\index{display}
and can be substituted wherever a 
{\tt xlib:display} is allowed\footnotemark\footnotetext{Implementation Note:
The {\tt contact-display} object
type could be implemented as a CLOS class, but its specification is intended to
permit other representations as well. A class definition may not be necessary,
since subclassing of this object type is not expected.
}.  An application will usually create a single {\tt contact-display} which
represents the connection through which requests are sent to an X server\index{X
Window System, server} and input events are received.

The basic operations on a {\tt contact-display} are listed below and are
described in detail in other
parts of this document.  
\begin{itemize}
\item Read and process an input event (see Section~\ref{ch:event-loop}).
\item Read character input from interactive stream contacts (see
Section~\ref{ch:multiple-stream-input}).
\item Establish global processing of input events (see
Section~\ref{ch:global-event-processing}).
\item Inquire the available display roots (see Section~\ref{ch:roots}).
\item Inquire or change the default display root (see
Section~\ref{ch:roots}).  
\end{itemize}

The {\tt open-contact-display} function is used to create a {\tt
contact-display} object and to connect it to an X server.\index{X Window System,
server}

{\large {\bf open-contact-display \hfill Function}} 
\index{open-contact-display function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & open-contact-display & \\ 
& (name \\
& \&key &  class\\
& &  (host *default-host*)\\
& &  (display *default-display*)\\
& &  before-actions\\
& &  (default-screen 0)\\
& &  authorization-name\\
& &  authorization-data\\
& &  protocol\\
& &  (root-class 'root))\\
(declare &(values  & contact-display)))
\end{tabular}
\rm
}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Creates and opens a new {\tt contact-display}. 
The {\tt
contact-display} is connected
to the X server\index{X Window System, server}
specified by {\tt host} and {\tt display}. 

}\end{flushright}


\begin{flushright} \parbox[t]{6.125in}{
{\tt name}
\begin{quote}
The application-specific name of the {\tt contact-display}. Technically,
this is an
application resource name symbol which is the top-level component of the
complete resource name for each application contact.  See
Section~\ref{ch:complete-names} for a discussion of complete resource names.
\end{quote}

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
{\tt class}
\begin{quote}
The application-specific class of the {\tt contact-display}. Technically,
this is an
application resource class symbol which is the top-level component of the
complete resource class for each application contact.  See
Section~\ref{ch:complete-names} for a discussion of complete resource
classes.
If omitted, this  defaults to the {\tt contact-display} name.
\end{quote}

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
{\tt host}
\begin{quote}
A host name for an X display server\footnotemark. If omitted, the value of the
special variable {\tt *default-host*}\index{*default-host*}\index{variables, *default-host*}
\index{X Window System, host}
is used. 
\end{quote}

}\end{flushright}
\footnotetext{The types of values allowed
for a host name depend on the implementation of CLX. Typically, host names are
strings.}

\begin{flushright} \parbox[t]{6.125in}{
{\tt display}
\begin{quote}
An integer identifying a display on the host. 
If omitted, the value of the
special variable {\tt
*default-display*}\index{*default-display*}\index{variables,
*default-display*} is used.
\end{quote}

}\end{flushright}


\begin{flushright} \parbox[t]{6.125in}{
{\tt before-actions}
\begin{quote}
A list of before actions which define application event
preprocessing. 
\index{before action}\index{actions, before} 
See Section~\ref{ch:before-actions}.  
\end{quote}

}\end{flushright}


\begin{flushright} \parbox[t]{6.125in}{
{\tt default-screen}
\begin{quote}
The index of the default {\tt xlib:screen}. This determines the default
{\tt contact-display} root
used to create contacts. See Section~\ref{ch:roots}.
\index{root, default}\index{contact-display, default root}
\index{contact-display, default screen} 
\end{quote}

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
{\tt authorization-name, authorization-data}
\begin{quote}
These options control a host-dependent access control facility.
See {\tt xlib:open-display} for a
description of these options.
\end{quote}

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
{\tt protocol}
\begin{quote}
Specifies the X protocol version and extension used.
See {\tt xlib:open-display} for a
description of this option.
\end{quote}

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
{\tt root-class}
\begin{quote}
Specifies the contact subclass used to create {\tt root} contacts.
\index{root}
This option is useful only for specialized clients such
as window managers.\index{window manager}
\end{quote}

}\end{flushright}

{\samepage
{\large {\bf *default-host* \hfill Variable}} 
\index{*default-host*}\index{variables, *default-host*}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defvar & *default-host* & nil)
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Used by {\tt open-contact-display} as the default host name.
If {\tt nil}, {\tt *default-host*} is set
to the {\tt :host} given the first time {\tt open-contact-display} is called.

}\end{flushright}


{\samepage
{\large {\bf *default-display* \hfill Variable}} 
\index{*default-display*}\index{variables, *default-display*}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defvar & *default-display* & 0)
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Used by {\tt open-contact-display} as the default host display id.
}\end{flushright}


\SAMEL{Events}{ch:events}
Input from an X server\index{X Window System, server} arrives
asynchronously in the form of {\bf input events}\index{event}.  
The basic set of input events and their contents are defined by the X Window
System protocol\index{X Window System, events}.

CLUE uses the {\tt event} class to represent an input event as an
object. The {\tt event} data structure has a slot for each value that appears in
any X input event (i.e.  each
keyword declared by a {\tt xlib:declare-event} form in CLX). 
For any actual input event, only a subset of the slots of the
corresponding {\tt event} object will be meaningful; the irrelevant slots
always have a {\tt nil} value.

\pagebreak
{\samepage
{\large {\bf event \hfill Class}} 
\index{event}
\index{classes, event}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{llll}
\raggedright
(defclass & event & \\ 
&()\\
&(above-sibling & atom & border-width\\
&character & child & code\\
&colormap & configure-p & contact\\
&count & data & display\\
&drawable & event-window & focus-p\\
&format & height & hint-p\\
&installed-p & key & keymap \\
& keysym &kind & major \\
& minor &mode & name \\
& new-p &override-redirect-p & parent \\
& place &property & requestor \\
& root &root-x & root-y \\
& same-screen-p &selection & send-event-p \\
& state &target & time \\
&type  & width & window \\
& x  & y)) 									     
\end{tabular}
\rm

}\end{flushright}}

The names and meanings of most {\tt event} slots are described by CLX\cite{clx}
and are not discussed in detail here. However, CLUE extends the basic event
representation to include the following  additional {\tt event} slots.

\begin{flushright} \parbox[t]{6.125in}{
{\tt character}
\begin{quote}
For {\tt :key-press} and {\tt :key-release} events, this slot contains the Common
Lisp character
object corresponding to the {\tt code}, the modifier {\tt state}, and the
current keymap of the display.
\end{quote}

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
{\tt contact}
\begin{quote}
The contact to which the event is dispatched.
\end{quote}

}\end{flushright}
\begin{flushright} \parbox[t]{6.125in}{
{\tt display}
\begin{quote}
The {\tt contact-display} from which the event was read.
\end{quote}

}\end{flushright}
\begin{flushright} \parbox[t]{6.125in}{
{\tt key}
\begin{quote}
An event keyword symbol which identifies the type of the event.
\end{quote}

}\end{flushright}
\begin{flushright} \parbox[t]{6.125in}{
{\tt keysym}
\begin{quote}
For {\tt :key-press} and {\tt :key-release} events, this slot contains the {\tt
xlib:keysym}
object corresponding to the {\tt code}. This slot is useful in the case where
the {\tt event-keysym} does not correspond to any Common Lisp character.
\end{quote}

}\end{flushright}
\begin{flushright} \parbox[t]{6.125in}{
{\tt name}
\begin{quote}
For a {\tt :timer} event, this slot contains the symbol which is the name of the
timer.  See Section~\ref{ch:timers}.
\end{quote}

}\end{flushright}


\SAMEL{Actions}{ch:actions}

An {\bf action}\index{actions} is a function which is called to
process an input event received by a contact instance. An action function
accepts an argument list consisting of a contact instance and possibly
additional arguments.\index{actions, argument list}
An action implements a response to
the given {\tt event} which is performed by all instances of a contact class.
Actions are often generic functions with methods defined for
specific contact classes.
All responses of a CLUE application to its user input are occur via
actions.  Typically, actions invoke contact callbacks\index{callback} in
order to report the results of user input back to the application.

In general, an action represents a well-defined contact behavior that
might be done in response to {\em any} event.  Contact programmers and
users can cooperate in defining how user events are bound to contact
actions (see Section~\ref{ch:event-translation}). In some cases,
however, an action may be designed to handle a very specific event type.
The {\tt with-event} macro can be used inside the body of an action in
order to access slots of the {\tt event} which caused the action to be
called.

{\large {\bf with-event \hfill Macro}} 
\index{with-event macro}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmacro & with-event & \\ 
& (slots \\
&  \&body  & body))
\end{tabular}
\rm

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Creates a lexical context in which the {\tt body} forms containing references to
the specified {\tt slots} of an {\tt event} instance are executed. This macro
may appear only inside the dynamic extent of {\tt process-next-event}.
\index{process-next-event function}
It allows actions and other functions to access slots of the event
currently being processed.

The {\tt slots} argument is a list which has the same syntax as in the CLOS
macro {\tt with-slots}. Each member of the {\tt slots} list is either an {\tt
event} slot name or a list of the form {\em (variable-name slot-name)}. The {\tt
body} may reference an {\tt event} slot only by using a slot name or {\em
variable-name} found in {\tt slots}.

Access to the current {\tt event} is intentionally restricted so that
implementation of {\tt event} objects can be optimized safely.

}\end{flushright}



The following actions are general utilities which are predefined by CLUE
for the basic {\tt contact} class.\index{actions, predefined}

{\samepage
{\large {\bf perform-callback \hfill Action, contact}}
\index{contact, perform-callback action}
\index{perform-callback action}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & perform-callback & \\
& ((contact  &contact)\\
& callback-name\\
& \&rest & args))
\end{tabular}
\rm
}\end{flushright}}
\begin{flushright} 
\parbox[t]{6.125in}{
Invokes the given callback via {\tt (apply-callback contact
callback-name args)}. }
\end{flushright}

{\samepage
{\large {\bf describe-action \hfill Action, contact}}
\index{contact, describe-action action}
\index{describe-action action}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & describe-action & \\
& ((contact  &contact)\\
& \&rest & exceptions))
\end{tabular}
\rm
}\end{flushright}}
\begin{flushright} 
\parbox[t]{6.125in}{
Prints a full description of the action event. Output is sent
to the stream given by the special variable {\tt
*trace-output*}.\index{*trace-output*}\index{variables, *trace-output*}
However, no description is printed if the action event type is a member
of the set of  event type
keywords given by {\tt exceptions}.}\end{flushright}

{\samepage
{\large {\bf eval-action \hfill Action, contact}}
\index{contact, eval-action action}
\index{eval-action action}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & eval-action & \\
& ((contact  &contact)\\
& \&rest & forms))
\end{tabular}
\rm
}\end{flushright}}
\begin{flushright} 
\parbox[t]{6.125in}{
Evaluates the given {\tt forms}.
The special variable {\tt *contact*}
\index{*contact*}\index{variables, *contact*}
is bound to {\tt contact}.
}\end{flushright}

{\samepage
{\large {\bf apply-action \hfill Action, contact}}
\index{contact, apply-action action}
\index{apply-action action}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & apply-action & \\
& ((contact  &contact)\\
& function \\
& \&rest & args))
\end{tabular}
\rm
}\end{flushright}}
\begin{flushright} 
\parbox[t]{6.125in}{
Calls the {\tt function} with the given arguments.
The special variable {\tt *contact*}
\index{*contact*}\index{variables, *contact*}
is bound to {\tt contact}.
}\end{flushright}


{\samepage
{\large {\bf throw-action \hfill Action, contact}}
\index{contact, throw-action action}
\index{throw-action action}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & throw-action & \\
& ((contact  &contact)\\
&  tag\\
& \&optional &  value))
\end{tabular}
\rm
}\end{flushright}}
\begin{flushright} 
\parbox[t]{6.125in}{
Throws to the {\tt tag}, returning the {\tt value}.}\end{flushright}

{\samepage
{\large {\bf trace-action \hfill Action, contact}}
\index{contact, trace-action action}
\index{trace-action action}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & trace-action & \\
& ((contact  &contact)\\
& \&rest & exceptions))
\end{tabular}
\rm
}\end{flushright}}
\begin{flushright} 
\parbox[t]{6.125in}{
Prints the the action event type and the {\tt contact} name. Output is sent
to the stream given by the special variable {\tt
*trace-output*}.\index{*trace-output*}\index{variables, *trace-output*}
However, nothing is printed if the action event type is a member
of the set of  event type
keywords given by {\tt exceptions}.}\end{flushright}

{\samepage
{\large {\bf ignore-action \hfill Action, contact}}
\index{contact, ignore-action action}
\index{ignore-action action}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & ignore-action & \\
& ((contact  &contact)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} 
\parbox[t]{6.125in}{
Used to notify the user that an event has been ignored. The primary method
sounds the bell at the X display server. 
}\end{flushright}

\SAMEL{Global Event Processing}{ch:global-event-processing}
CLUE defines operations on a {\tt contact-display} object that provide for global
event processing that is independent of the event processing implemented by individual
contact instances.\index{input, global}

\LOWERL{Before Actions}{ch:before-actions}

A {\bf before action}\index{before action}\index{actions, before}
\index{actions} of a {\tt contact-display} is an action which is called
when an event is dispatched to a contact, but before any other contact input
processing is performed.  Before actions are useful for implementing
various kinds of application-dependent event preprocessing. For example, an
application could define a before action for the {\tt contact} class that will
record every event in a log file. 

Associated with a {\tt contact-display} is a list of before actions. 
Each event received by a {\tt contact-display} is compared with every element of
its before actions list.  If {\tt c} is the class for which the before
action is defined, and if {\tt contact} is the contact instance to which the
event has been dispatched, then the before action is called if {\tt (typep
contact c)} is true.

The following functions control the before actions of a {\tt
contact-display}.

\pagebreak
{\large {\bf add-before-action \hfill Function, contact-display}} 
\index{add-before-action function}
\index{contact-display, add-before-action function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & add-before-action & \\ 
& (contact-display\\
& class\\
& action\\
& \&rest & arguments))
\end{tabular}
\rm

}\end{flushright}



\begin{flushright} \parbox[t]{6.125in} { Adds a new before action for the given
{\tt class} to the {\tt contact-display}.  The {\tt action} replaces any
existing before action with the same name and class.  Any {\tt arguments} given
will be passed to the {\tt action} when it is called.  The {\tt arguments} must
correspond to the lambda-list of the {\tt action} function.

}\end{flushright}

{\samepage
{\large {\bf delete-before-action \hfill Function, contact-display}} 
\index{delete-before-action function}
\index{contact-display, delete-before-action function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & delete-before-action & \\ 
& (contact-display\\
& class\\
& action))
\end{tabular}
\rm

}\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{ Removes from the {\tt
contact-display} any existing before action whose name is given by the {\tt
action} symbol and whose class is given by the {\tt class} symbol .

}\end{flushright}


{\large {\bf before-actions \hfill Function, contact-display}} 
\index{before-actions function}
\index{contact-display, before-actions function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & before-actions & \\ 
& (contact-display)\\
(declare &(values  & actions)))
\end{tabular}
\rm

}\end{flushright}


\begin{flushright} \parbox[t]{6.125in}{
Returns the list of before actions for the {\tt
contact-display}. Each element of the list returned is a list of the form {\tt
({\em class-name action-name argument*})}.

}\end{flushright}



\SAMEL{Modal Input}{ch:modal-input}
(to be completed)\index{INCOMPLETE!}

{\samepage
\HIGHERL{The Event Loop}{ch:event-loop}
The {\tt process-next-event} function implements the body of the application event
loop.\index{event loop}
{\tt process-next-event} reads an input
event from a {\tt contact-display} and
dispatches it for processing.
Using this function, a typical application event loop will have the form shown
below.\index{event loop, example} 
}

\begin{verbatim}
(catch loop-exit-tag 
  (loop 
    (process-next-event contact-display)))
\end{verbatim}

The event loop should be terminated by a {\tt throw} to an application-defined 
{\tt loop-exit-tag}.\index{event loop, terminating}


{\large {\bf process-next-event \hfill Function, contact-display}}
\index{contact-display, process-next-event function}
\index{process-next-event function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & process-next-event & \\
& (contact-display\\
& \&key & timeout))
\end{tabular}
\rm

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Reads the next input event  from the {\tt contact-display} and processes it. If no
event is received within the specified {\tt
timeout} interval (given in seconds), then {\tt process-next-event} returns {\tt
nil}; a {\tt timeout} of {\tt nil} means to wait forever. Otherwise, {\tt
process-next-event} returns {\tt t}.

Before reading an event, {\tt process-next-event} calls {\tt update-state} to
ensure that the display is consistent with the current state of contacts
belonging to the {\tt contact-display} (see Section~\ref{ch:contact-state}).
\index{update-state function}

After an event has been read, the following algorithm is used.
\begin{itemize}
\item  The contact receiving the event is determined.
\item  All  before actions\index{before action}\index{actions, before} defined
for subclasses of the contact's class are called.  
\item The contact's {\tt handle-event}
method is called. The {\tt handle-event} method invokes the process of
``event translation,''\index{event, translation}
during which the appropriate actions are called to handle the event. See
Section~\ref{ch:event-translation}) for a complete description of event translation.
\end{itemize} }\end{flushright}


\SAMEL{Synchronizing Event Processing}{ch:sync}
\index{synchronization}
\index{event, synchronizing} 
A complex operation, such as
presenting a large contact tree, often takes the form of a ``chain reaction,''
wherein the input events which precipitate from contact actions are processed to
invoke still more actions and events, etc.  In order to synchronize its user
interface, an application will sometimes need to wait until the complete chain
of events has been processed before continuing the event loop.
This synchronization of event processing is achieved by using the {\tt
process-all-events} function.


{\samepage
{\large {\bf process-all-events \hfill Function, contact-display}}
\index{contact-display, process-all-events function}
\index{process-all-events function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & process-all-events & \\ 
& (contact-display))
\end{tabular}
\rm

}\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{
Any buffered requests are sent and all resulting input events are processed,
using the following algorithm.
\begin{itemize}
\item Call {\tt (xlib:display-finish-output contact-display)} to send any
buffered requests and receive any resulting events.
\item If any events were received, process each of them via {\tt
(process-next-event contact-display :timeout 0)} and then repeat the previous
step.  \end{itemize}

}\end{flushright}


\SAMEL{Timers}{ch:timers}
CLUE provides support for animation\index{animation} and other types of
time-sensitive user interfaces via objects 
called {\bf timers}\index{timer}.
A timer is a source of {\tt :timer} events, inserting them into the event stream
of a {\tt contact-display} according to a specific time interval. A timer causes
{\tt :timer} events to be dispatched to a specific contact for processing.

A {\tt :timer} event is
defined by CLUE and is represented by an {\tt event} object with the following
non-{\tt nil} slot values.
\index{event, :timer}

\begin{center} 
\tt
\begin{tabular}{lll}
key       & :timer\\
contact   & {\em timer contact}\\
name      & {\em timer name}\\
data      & {\em timer data}\\
display      & {\em contact-display}
\end{tabular}
\rm
\end{center}

Timers are abstract ``objects'' that are not actually represented as CLOS class
instances, but instead are defined solely by the following functional
interfaces.

{\samepage
{\large {\bf add-timer \hfill Function, contact}} 
\index{add-timer function}
\index{contact, add-timer function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & add-timer & \\ 
& (contact\\ 
& name\\
& interval\\
& \&optional & data)\\
(declare & (values  & name)))
\end{tabular}
\rm

}\end{flushright}
}

\begin{flushright} \parbox[t]{6.125in}{ Creates a timer with the given {\tt
name} symbol.  The new timer replaces any existing timer with the same name. The
new timer sends a {\tt :timer} event to the {\tt contact-display}
associated with the given {\tt contact} each time the specified time {\tt
interval} (given in seconds) elapses\footnotemark.  Such {\tt :timer} events 
are dispatched to the given {\tt contact} and also contain any given application
{\tt data} (see description of {\tt :timer} event above). The timer {\tt name} is
returned.

A timer is automatically destroyed when its associated {\tt contact} is
destroyed.

}\end{flushright}
\footnotetext{Implementation Note: An implementation is
permitted to check for the next elapsed timer interval only before reading the
next input event. This may affect timing accuracy when an event results in
lengthy application processing.}

{\large {\bf delete-timer \hfill Function, contact}} 
\index{delete-timer function}
\index{contact, delete-timer function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & delete-timer & \\ 
& (contact\\ 
& \&optional name))
\end{tabular}
\rm

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{Destroys the {\tt contact} timer
with the specified {\tt name}. If no {\tt name} is given, then all timers
belonging to the {\tt
contact} are destroyed. The return value is {\tt nil} if and
only if no {\tt contact} timer of the given {\tt name} exists.

\rm

}\end{flushright}

{\samepage
\SAMEL{Contact Input Programming}{ch:contact-input-programming}
This section describes the CLUE interfaces used by a contact programmer to
define contact input responses.

\LOWERL{Event Specifications}{ch:event-specifications}
CLUE input processing consists of matching an event with an event specification
found in a contact's {\tt event-translations} slot, and then calling actions
associated with the matching event specification.
An {\bf event specification}\index{event specification} is a notation for
describing a specific type of event. Syntactically, it is one of the
following.
}

\parbox[t]{.75in}{{\em event key}}\parbox[t]{5.75in}{
A keyword symbol which is the name for an event type (i.e.\ the value of the {\tt
key} slot of an {\tt event} object). This form of event specification
matches any {\tt event} which has this {\tt key}.} 

\parbox[t]{.75in}{{\em character}}\parbox[t]{5.75in}{
A Common Lisp character object. This form of event specification matches any
{\tt :key-press} event with this object as its {\tt character}.}

\parbox[t]{.75in}{{\em list}}\parbox[t]{5.75in}{
A list of the form {\tt ({\em keyword} {\em value}*)}. Certain list forms are
already defined by CLUE and are described below. Programmers can define new list
forms using the interfaces described in
Section~\ref{ch:new-event-specifications}.}

{\samepage
\index{motion-notify events}
{\tt (:motion-notify [{\em state} [{\em select}]])}\\
\hspace*{.75in}
\parbox[t]{5.75in}{
\begin{tabbing}
{\em state-key} \= ::= \= \kill
{\em state}     \>::= \>{\tt :none} $|$ {\tt :any} $|$ {\em state-key} $|$
                      ({\em state-key}*) $|$ {\em xlib:mask16} \\
\\
{\em select}   \>::= \>{\tt :same} $|$ {\tt :all} $|$ {\em state-key} $|$
                      ({\em state-key}*) $|$ {\em xlib:mask16} \\
\\
{\em state-key} \>::= \>{\tt :shift} $|$ {\tt :lock} $|$ {\tt :control} $|$ \\
                \>    \>{\tt :mod-1} $|$ {\tt :mod-2} $|$ {\tt :mod-3} $|$ {\tt :mod-4} $|$
{\tt :mod-5} $|$ \\
                \>    \>{\tt :meta} $|$ {\tt :super} $|$ {\tt :hyper} $|$\\
                \>    \>{\tt :button-1} $|$ {\tt :button-2} $|$ {\tt :button-3} $|$ {\tt
:button-4} $|$ {\tt :button-5}\\
\end{tabbing}}
}
\begin{flushright}
\parbox[t]{5.75in}{
This
form of event specification matches any {\tt :motion-notify}
event with the given state of the
modifier keys.
The {\em state} and {\em select} options are used to specify the state of the
modifier keys required for an {\tt event} to match the event specification.
}

\parbox[t]{5.75in}{
{\em state} is a set which specifies the state of modifier keys: the
down state for modifier keys which belong to {\em state} and the up
state for those that do not.  
{\em state} defaults to {\tt :none}, which is equivalent to the empty set.
{\em select} specifies the set of modifier keys whose state is examined
during matching. {\em select} defaults to {\tt :same}, which means
``same as the {\em state} set''. The {\em select} value {\tt :all}
means that
all modifier keys are considered.
The {\em state} value {\tt :any} is a more readable notation for the default
values; it is equivalent to a {\em state} of {\tt :none} and a {\em select} of
{\tt :same}.
Either {\em state} or {\em select} may given as a bit string (i.e. an {\tt
xlib:mask16} value) in which a 1 bit means that the corresponding
modifier key is an element of the set.
}

\parbox[t]{5.75in}{
A {\tt :motion-notify} event matches the event specification only if the
following conditions are satisfied.
\begin{itemize}
\item Every modifier key in {\em select} has the state (up or down)
indicated by {\em state}. 
\item If there are modifiers keys in {\em state} which do {\em not}
belong to {\em select}, then at least one of
them is down.  This is a way to treat such a set of modifiers as
``equivalents'' without requiring a specific state for each of them.
\end{itemize}
}
\end{flushright}

{\samepage
\index{button-press events}\index{button-release events}
{\tt (:button-press [{\em button} [{\em bstate} [{\em select}]]])}\\
{\tt (:button-release [{\em button} [{\em bstate} [{\em select}]]])}\\
\hspace*{.75in}
\parbox[t]{5.75in}{
\begin{tabbing}
{\em click-state-key} \= ::= \= \kill
{\em button} \>::= \>{\tt :any} $|$ {\tt :button-1} $|$ {\tt :button-2} $|$
{\tt :button-3} $|$ {\tt :button-4} $|$ {\tt :button-5}\\
\\
{\em bstate} \>::= \>{\tt :none} $|$ {\tt :any} $|$ {\em click-state-key} $|$
                      ({\em click-state-key}*) $|$ {\em xlib:mask16} \\
\\
{\em click-state-key} \>::= \>{\tt :shift} $|$ {\tt :lock} $|$ {\tt :control} $|$ \\
                \>    \>{\tt :mod-1} $|$ {\tt :mod-2} $|$ {\tt :mod-3} $|$ {\tt :mod-4} $|$ {\tt :mod-5} $|$ \\
                \>    \>{\tt :meta} $|$ {\tt :super} $|$ {\tt :hyper} $|$\\
                \>    \>{\tt :button-1} $|$ {\tt :button-2} $|$ {\tt :button-3} $|$ {\tt
:button-4} $|$ {\tt :button-5} $|$\\
                \>      \> {\tt :single-click} $|$ {\tt :double-click}\\ 

\end{tabbing}}
}
\begin{flushright}
\parbox[t]{5.75in}{
This form of event specification matches any {\tt :button-press} or {\tt
:button-release} event with the given state of the modifier keys.  If
{\em button} is given, then only events with the given button in {\tt
event-code} are matched.  By default, {\em button} is {\tt :any}, in
which case the {\tt event-code} is ignored during matching.  }

\parbox[t]{5.75in}{
The {\em select} option operates as described above. The {\em bstate}
option operates the same as the {\em state} option above. However, {\em
bstate} may also contain either a {\tt :single-click} or a {\tt :double-click}
keyword. These keywords, which control the matching of ``double-click''
events, are described in Section~\ref{ch:double-click}.
\index{event, double-click}\index{double-click event}
}
\end{flushright}

\pagebreak
{\samepage
\index{key-press events}\index{key-release events}
{\tt (:key-press [{\em key} [{\em state} [{\em select}]]])}\\
{\tt (:key-release [{\em key} [{\em state} [{\em select}]]])}\\
{\tt (:up {\em character})}\\
\hspace*{.75in}
\parbox[t]{5.75in}{
\begin{tabbing}
{\em key} \= ::= \= \kill
{\em key}       \>::= \>{\em character} $|$ {\em keysym} $|$ {\tt :any} \\
\end{tabbing}}}
\begin{flushright}
\parbox[t]{5.75in}{
This
form of event specification matches any {\tt :key-press} or {\tt :key-release}
event with the given {\tt event-character} or {\tt event-keysym} and with the
given state of the modifier keys. By default, {\em key} is {\tt :any}, in which
case the {\tt event-character} and {\tt event-keysym} are ignored during
matching.
{\tt (:up {\em
character})} is an abbreviation for {\tt (:key-release {\em character})}.
A {\em character} is typically a Common Lisp character object, but in general
it can be any object associated with a {\em keysym} via the {\tt
xlib:define-keysym} function (see CLX\cite{clx}).}

\parbox[t]{5.75in}{
The {\em state} and {\em select}
options operate as described above. However, for this form of event
specification, when {\em key} is a character, then the default value of
{\em select} is 0 (i.e. no modifier keys are selected). This is because
the character object already contains modifier state information, as a
result of the keysym-to-character transformation done by CLX.
}
\end{flushright} 

{\samepage
\index{client-message events}
{\tt (:client-message {\em type} {\em accessor-value*})}\\
\hspace*{.75in}
\parbox[t]{5.75in}{
\begin{tabbing}
{\em accessor-value} \= ::= \= \kill
{\em accessor-value} \>::= \>{\em function} {\em value} \\
\end{tabbing}}
}
\begin{flushright}
\parbox[t]{5.75in}{
This
form of event specification matches a {\tt :client-message}
event when its {\tt type} slot matches the given {\em type}. The {\em
type} must be an {\tt xlib:xatom}. If
any accessor function/value pairs are
given, then the {\tt data} slot of the {\tt :client-message} event must
match each function/value. That is, {\tt (equal (funcall {\em function}
data) {\em value})} must be true for each {\em accessor-value}.
During accessor matching, the special variable {\tt *event-display*} is
bound to the {\tt display} slot of the event. The event display may be
needed to convert X resource id numbers in the {\tt data} into the form
used in CLX and CLUE.}
\end{flushright}
 
\SAMEL{Defining New Event Specifications}{ch:new-event-specifications}

The syntax for event specifications can be extended to include new
specification list forms defined by the programmer. 
\index{event specification, extended syntax}
The most general
form of an event specification list is {\tt ({\em keyword-symbol
argument*})}. The CLUE interface to this general form is defined by two
functions: a check function, which verifies the syntactical
correctness of the list, and a match function, which matches {\tt event}
objects with the list. The check  function for a {\em keyword-symbol}
may be returned or changed by the {\tt check-function} macro. 

{\samepage
{\large {\bf check-function \hfill Macro}} 
\index{check-function macro}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmacro & check-function & \\ 
& (keyword) \\
(declare &(type keyword & keyword))\\
(declare &(values  & function)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns or (with {\tt setf}) changes the check function for the given
event type {\tt keyword}. The {\tt keyword} must be an event key defined
by CLX.

}\end{flushright}


{\samepage
The general interfaces
required for  check/match functions are described below.


\index{event specification, check function}
\index{check function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & a-check-function & \\ 
& (\&rest & event-spec) \\
(declare &(values  & match-function-spec\\
         &         & canonical-event-key)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
A check function is defined by the {\tt check-function} macro. It
is called to validate an event specification list whose first element is
the {\em keyword-symbol}.

A check function signals an error if the {\tt event-spec} is syntactically
invalid.  Otherwise, the first return value
is a list of the form {\tt ({\em match-function} . {\em
canonical-event-spec})}. The {\tt car} of this list is a function
object which is the corresponding match function. The {\tt cdr} of
the list is the event
specification in its ``canonical form'' (i.e.\  the form required by the match
function). The check and match functions can thus establish an internal form of
the event specification which optimizes matching. The second return value, if
non-{\tt nil}, is a different event key to be used during matching. For example,
the default check function for {\tt :up} will return {\tt :key-release}
as its second value.

}\end{flushright}


\index{event specification, match function}
\index{match function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & a-match-function & \\ 
& (event \\
& \&rest & canonical-event-spec) \\
(declare &(values  & boolean)))
\end{tabular}
\rm

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
A match function is returned by the check function of a
{\em keyword-symbol}. It
is called to match an {\tt event} with an event specification list whose
first element is the {\em keyword-symbol}.

A match function is a predicate which returns non-{\tt nil} if the {\tt
canonical-event-spec} computed by the corresponding check function matches the
given {\tt event}.


}\end{flushright}


\SAMEL{Event Translation}{ch:event-translation}

\index{event, translation}
If an input event is received by a specific window, then that window is given as
a slot value in the corresponding {\tt event} object. CLUE begins by determining
the contact corresponding to the event window and  calling the contact's
{\tt handle-event} method. 
\index{handle-event method}
Subsequent contact event processing
involves ``translating'' the event into calls to the appropriate
actions\index{actions} and is controlled by the contact's {\tt
event-translations} slot and its class event translations.
\index{class event translation}\index{event translation, class event translation}

The {\tt event-translations} slot contains a lookup
table\footnotemark\footnotetext{Implementation Note: The {\tt
event-translations} slot is
conceptually an association list but need not be implemented as one.}
whose elements
are {\bf event translations}\index{event translation}. Each event
translation is a list of the form {\tt ({\em event-specification} {\em name*})},
where each {\em name} is either an action name or a list of
the form {\tt ({\em action-name argument*})} . 
Thus, each event translation in {\tt event-translations} associates  an event
specification with one or more actions and, 
for each action, an optional argument
list.  The event translations in a contact's {\tt event-translations} slot can
be modified by the functions {\tt add-event} and {\tt delete-event}.
\index{delete-event function}\index{add-event function}  


{\bf Class event translations}\index{class event translation} are event translations which
belong to all instances of a contact class. A class event translation is created by
the {\tt defevent} macro.\index{defevent macro}

Basic contact event processing consists of the following steps:
\begin{itemize}
\item For each event translation in the contact's {\tt event-translations}:
\begin{itemize}
\item The event is matched with the event specification found in the event
translation. Matching is done using the match function for the event type defined by
the event specification.\index{event specification, match function}
\item If a match occurs, then each of
the actions in the event translation is called and event processing terminates.
Any arguments from the matching event translation are given to the actions.
\end{itemize}
\item If no match is found in the previous step, then the contact's class event
translations are examined. Starting with the class of the contact, then for each
class event translation of the class: 
\begin{itemize}
\item The event is matched against the event specification found in the class
event translation. 
\item If a match occurs, then each of
the actions in the event translation is called, using any arguments given, and 
event processing terminates.
\end{itemize}
\item If no match is found, then the previous step is repeated for the next
class in the class precedence list.  
\end{itemize}
 

This method of structuring contact event processing allows a user and a contact
programmer to cooperate in defining a contact's input behavior.
Event translations are a contact resource; they can be read from a
user-defined resource
database\index{resource, database} and used to initialize a contact's {\tt
event-translations} when
the contact is created (see Chapter~\ref{ch:resource-management}
for a complete discussion of contact resource management). Event translations
express user preferences for the mapping between input events and 
actions. On the other hand, only the contact programmer can determine the
methods which actually implement the actions.
The contact programmer can also provide class event translations to define default
input behavior shared by all instances of a contact class.

\index{contact, event mask}\index{event mask}
Most types of events can be received by a contact only if they are selected by
the contact's {\tt event-mask}.  CLUE automatically initializes a contact's {\tt
event-mask} slot to select all event types referenced by its {\tt
event-translations} slot and its class event translations.  The {\tt event-mask}
is also modified appropriately by {\tt add-event} and {\tt delete-event}.
As a result, CLUE programmers rarely need to modify a contact's {\tt event-mask}
slot directly.

CLUE initiates contact event processing by calling the contact's {\tt
handle-event} method.  By default, this method simply processes an event
according to the contact's event translations and class event
translations. 
However, some
contact classes may redefine the {\tt
handle-event} method in order to add input processing unrelated to event
translations.
{\tt handle-event} calls {\tt translate-event} in order to determine
which actions will be invoked.


{\samepage
{\large {\bf handle-event \hfill Method, contact}}
\index{contact, handle-event method}
\index{handle-event method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & handle-event & \\
& ((contact  &contact)\\ 
& event))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Performs all contact processing for the given event. 
The primary method for the {\tt contact} class calls {\tt
translate-event} and invokes all actions that match the {\tt event}.

}\end{flushright}

{\samepage 
{\large {\bf translate-event \hfill Function, contact}}
\index{contact, translate-event function}
\index{translate-event function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & translate-event & \\
& (contact\\
& event) \\
(declare &(values &actions)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Looks up the event translation that matches the {\tt event}, using the
algorithm described in Section~\ref{ch:event-translation}, and returns
the list of actions found in the matching event translation.

}\end{flushright}

{\samepage
{\large {\bf add-event \hfill Function, contact}} 
\index{contact, add-event function} 
\index{add-event function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & add-event & \\ 
& (contact\\
&  event-spec\\
& \&rest & actions))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Creates an event translation associating the event specification with the given 
action symbols in the
contact's {\tt event-translations}.
Each additional argument is either an action name symbol or a list of the form
{\tt ({\em action-name argument*})}.  
If an event translation for the given event specification already exists, then
its previous actions are replaced by the new {\tt actions}, without changing its
position in the {\tt event-translations}. Otherwise, a new event translation is
created and added as the first element of the {\tt
event-translations}.  
}\end{flushright}

{\samepage
{\large {\bf delete-event \hfill Function, contact}}
\index{contact, delete-event function} 
\index{delete-event function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & delete-event & \\ 
& (contact\\
&  event-spec))
\end{tabular}
\rm

}\end{flushright}
}

\begin{flushright} \parbox[t]{6.125in}{
Removes any event translation for the event specification  from the
contact's {\tt event-translations}. 

}\end{flushright}


{\samepage
{\large {\bf event-actions \hfill Function, contact}}
\index{contact, event-actions function} 
\index{event-actions function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & event-actions & \\ 
& (contact\\
&  event-spec)\\
(declare & (values actions)))
\end{tabular}
\rm

}\end{flushright}
}

\begin{flushright} \parbox[t]{6.125in}{
Returns a list of {\tt actions} associated with the given {\tt contact} and
event specification. 
Each element of the returned  {\tt actions} list is either an action name symbol
or a list of the form {\tt ({\em action-name argument*})}.  

A process similar to that used by {\tt translate-event} is used to locate an
event translation containing the {\tt event-spec}, either in the {\tt contact}'s
{\tt event-translations} or among its class event translations. If no such event
translation is found, then {\tt nil} is returned.

}\end{flushright}



{\samepage
{\large {\bf defevent \hfill Macro}} 
\index{defevent macro}
\index{class event translation}\index{event translation, class event translation}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmacro & defevent \\ 
& (class\\
&  event-spec\\
& \&rest & actions))
\end{tabular}
\rm

}\end{flushright}
}

\begin{flushright} \parbox[t]{6.125in}{
Creates a class event translation for the {\tt class}.
Each additional argument is either an action name symbol or a list of the form
{\tt ({\em action-name argument*})}.
The new event translation replaces
any existing class event translation for the same event specification.

}\end{flushright}

{\large {\bf undefevent \hfill Macro}} 
\index{undefevent macro}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmacro & undefevent \\ 
& (class\\
&  event-spec\\
& \&rest & actions))
\end{tabular}
\rm

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Deletes a class event translation for the {\tt class}.
The {\tt actions} are ignored; they are included only for consistency with the
syntax  of {\tt defevent}. }\end{flushright}

{\samepage
{\large {\bf describe-event-translations \hfill Function}} 
\index{describe-event-translations function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & describe-event-translations \\ 
& (contact\\
&  \&optional & (stream *standard-output*)))
\end{tabular}
\rm

}\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{
Prints a description of the event translations for a contact class or a contact
instance on the given stream. If {\tt contact} is a class symbol, then this
function prints a description of each class event translation for the given class
and for each superclass in its class precedence list. If {\tt contact} is a
contact instance, then the contents of its {\tt event-translations} is also
printed.

}\end{flushright}


\SAMEL{Double-click Events}{ch:double-click} 
\index{event, double-click}\index{double-click event} 
CLUE provides for the automatic
recognition of ``double-clicks'' by treating these as specially
modified {\tt :button-press} or {\tt :button-release} events.  A
``click'' is a {\tt :button-press} event followed immediately by a {\tt
:button-release} event for the same button, with no intervening change
in pointer position\footnotemark\footnotetext{Implementation Note:
In practice, very small pointer
movements (``jitter'') should be ignored during double-click processing.} or modifier
key state.  A ``double-click''
is a sequence of two clicks of the same button in rapid succession.  The
definition of a double-click ``event'' is thus time-sensitive; for a
double-click to be recognized, the time interval between events in the
sequence cannot exceed a certain maximum.  The {\tt
display-multipress-delay-limit} accessor defines the maximum
inter-event time
interval, in milliseconds,
for a given {\tt contact-display}.\index{display-multipress-delay-limit
macro}

During event translation for a {\tt :button-press} event, CLUE will
invoke double-click processing when it attempts to match a {\tt
:button-press} event specification
containing the {\tt :double-click} keyword (see
Section~\ref{ch:event-specifications}).  CLUE then
looks ahead into the event stream, checking for the remainder of the
double-click sequence. If a double-click is recognized, then the event
specification is matched, the corresponding actions are invoked with the
initial {\tt :button-press} event, and the rest of the double-click
events are discarded. Otherwise, the match fails, all events remain in
the event stream, and event translation continues.
The {\tt :double-click} keyword can also appear in a {\tt
:button-release} event specification. In this case, CLUE attempts to
match the event specification by looking ahead for
a subsequent click sequence. If a click is found, then the event
specification is matched, the corresponding actions are invoked with the
initial {\tt :button-release} event, and the rest of the click
events are discarded. Otherwise, the match fails, all events remain in
the event stream, and event translation continues.

The {\tt :single-click} keyword can be used to explicitly request CLUE
double-click processing, in order to verify that a double-click sequence
has {\em not} occurred. An event specification containing the
{\tt :single-click} keyword will be matched only when the event is not
followed by the rest of a
double-click sequence. This form of event specification allows a contact
to reliably specify actions for both single- and double-click event
sequences, with no dependence on the relative order of {\tt
:single-click} and {\tt :double-click} event translations.

Detecting when the {\tt display-multipress-delay-limit} timeout has lapsed is
complicated by the possibility of network delays in
receiving events from the X server.\index{X Window System, server} 
Timestamps maintained by the X server can be used to verify a timeout, at
the expense of a message round-trip between the client and
the server. CLUE clients can optionally select such timeout
verification for a {\tt contact-display} by using the {\tt
display-multipress-verify-p} accessor.
\index{display-multipress-verify-p macro}


{\samepage
{\large {\bf display-multipress-delay-limit \hfill Macro, contact-display}} 
\index{display-multipress-delay-limit macro}
\index{contact-display, display-multipress-delay-limit macro}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmacro & display-multipress-delay-limit & \\ 
& (contact-display) \\
(declare &(values  & number)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns or (with {\tt setf}) changes the multipress delay limit timeout
for the given {\tt contact-display}. This defines the maximum
inter-event time
interval, in milliseconds, for a multipress event sequence to be
recognizable. The default value is given by the
{\tt *default-multipress-delay-limit*} special variable.
}\end{flushright}

{\samepage
{\large {\bf display-multipress-verify-p \hfill Macro, contact-display}} 
\index{display-multipress-verify-p macro}
\index{contact-display, display-multipress-verify-p macro}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmacro & display-multipress-verify-p & \\ 
& (contact-display) \\
(declare &(values  & number)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns or (with {\tt setf}) changes the way that multipress event
sequences are verified for the given {\tt contact-display}. When true, 
timeout is verified by requesting
a timestamp from the X server. When {\tt nil}, multipress handling
will be faster but some double-clicks may be incorrectly interpreted as
two single-clicks. 
The default
value is given by the {\tt *default-multipress-verify-p*} special variable.
}\end{flushright}


{\samepage
{\large {\bf *default-multipress-delay-limit* \hfill Variable}} 
\index{*default-multipress-delay-limit*}\index{variables, *default-multipress-delay-limit*}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defvar & *default-multipress-delay-limit* & 250)
\end{tabular}
\rm

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
The default maximum number of milliseconds between events in a
multipress sequence.

}\end{flushright}}


{\samepage
{\large {\bf *default-multipress-verify-p* \hfill Variable}} 
\index{*default-multipress-verify-p*}\index{variables, *default-multipress-verify-p*}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defvar & *default-multipress-verify-p* & t)
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
The default multipress timeout verification switch.  When true, timeout
of multipress events is verified by requesting a
timestamp from the X server.  When {\tt nil}, multipress handling will
be faster but some double-clicks may be incorrectly interpreted as two
single-clicks.

}\end{flushright}

\SAMEL{Contact Sensitivity}{ch:sensitive}
Occasionally, an application may want a component of its user interface to be
visible but temporarily unavailable for input. For example, a menu might be used
to present all application commands, although some commands may
not be valid at all times.
Therefore, a contact can either be ``sensitive'' or ``insensitive'' to input.
\index{sensitivity}
\index{contact, sensitivity}
\index{input, sensitivity}
When a contact is insensitive, events of the following type are not dispatched
to the contact and are ignored.
\begin{itemize}
\item {\tt :button-press}
\item {\tt :button-release}
\item {\tt :enter-notify}
\item {\tt :focus-in}
\item {\tt :focus-out}
\item {\tt :key-press}
\item {\tt :key-release}
\item {\tt :leave-notify}
\item {\tt :motion-notify}
\end{itemize}
Also, the sensitivity of a contact is typically represented visually. For
example, an insensitive contact may be displayed in a distinctive color, greyed
out, or stippled.

A contact is insensitive if the value of its {\tt sensitive} slot is {\tt
:off}, or if its parent is insensitive. Conversely, a contact is sensitive if and
only if it and all of its ancestors have a   value  of {\tt :on} for {\tt
sensitive}.

\SAMEL{Event Compression}{ch:compression}
\index{input, compression}\index{event, compression}
CLUE allows the programmer defining a contact class to ignore certain redundant
input events in order to improve contact performance. ``Compression'' of
redundant events is controlled by the class slots {\tt compress-exposures} and
{\tt compress-motion}, which are shared by all instances of a contact class.

Contacts which respond to changes in the pointer position may find it difficult
to keep up with a rapidly-moving mouse and, in fact, may not need to recognize every
individual motion event. Initializing the {\tt compress-motion} slot to {\tt
:on} will cause all but the last in a sequence of consecutive {\tt :motion-notify}
events to be
ignored, with only the most recent event being dispatched to the contact.

Simple contacts may find it more efficient always to display the entire contact
image, ignoring {\tt x}, {\tt y}, {\tt width}, and {\tt height} arguments
to the {\tt display} method.
\index{display method}
  Such contacts will not be interested in partial
exposure events.  Initializing the {\tt compress-exposures} slot to {\tt :on} will
result in {\tt :exposure} events being dispatched to the contact only when the
expose count is zero (i.e.  the last of a series of partial exposure events).



\CHAPTERL{Contact Hierarchy}{ch:contact-hierarchy}

\LOWERL{Composites}{ch:composites}
A contact which is the parent of another contact is known as a
{\bf composite}\index{composite}. A composite 
may be the parent of another composite, leading to a
tree-structured contact hierarchy. Contact A is said to be an
{\bf ancestor}\index{ancestor} of contact B (its 
{\bf descendant}\index{descendant}) when
A is B's parent or an ancestor of B's parent. 

A composite represents a set of contacts which can be manipulated
(positioned, presented,
etc.) as a unit.  A composite is useful whenever several contacts act in concert to provide a
single component of the application's user interface.  Typical examples include
``control panels'' and ``dialog boxes'' --- groups of contacts that are presented
together and are used to make related adjustments to application data.  In some
cases, operations on one member of such a structure may change the appearance of
another.  The composite is the mechanism which allows the operations of its
members to be coordinated.

The fundamental aspects of the contact parent-child relationship are the same as
those of the window hierarchy defined by the X Window System. In addition, a
composite furnishes geometry management and focus management services for
its children.

A composite is an instance of the {\tt composite} class, a
subclass of the basic {\tt contact} class.

{\samepage
{\large {\bf composite \hfill Class}} 
\index{classes, composite}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defcontact & composite  & \\ 
& (contact) & \\
& ((children  & :type list\\
&     & :initform nil\\
&     & :reader composite-children)\\
& (focus  & :type contact\\
&     & :initform nil\\
&     & :reader composite-focus)\\
& (shells &:type list \\        
&     & :initform nil\\
&     & :reader composite-shells))\\
(:resources\\
&(event-mask & :type (or null xlib:event-mask)\\
&	     & :initform (xlib:make-event-mask))\\
&(focus-name & :type symbol)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
{\tt children}
\begin{quote}
A list of the contacts which are the children of the composite. 
CLUE automatically ensures that this slot value is always consistent with the
window hierarchy stored by the X server.
This slot should be modified only as a side-effect of contact creation, 
destruction, and reparenting; it should
never be modified directly.
\end{quote}
}\end{flushright}


\begin{flushright} \parbox[t]{6.125in}{
{\tt focus}
\begin{quote}
\index{input, focus}
The member of {\tt children} which is currently designated as the keyboard input
focus for the composite. This slot is {\tt nil} if no focus has been designated.
Designating a contact as  the composite {\tt focus} does not necessarily redirect
keyboard events. Rather, the {\tt focus} is the current ``keyboard
representative'' for the composite; assigning the keyboard focus to the
composite then usually results in assigning it to the {\tt focus}
contact.  \end{quote} }\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
{\tt shells}
\begin{quote}
A list of {\tt shell} contacts owned by the composite. See Section~\ref{ch:shells}
\end{quote} }\end{flushright}

{\samepage
{\large {\bf add-child \hfill Method, composite}}
\index{composite, add-child method}
\index{add-child method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & add-child & \\
& ((composite  &composite)\\
& child\\
& \&key))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Called automatically when the {\tt child} contact become a child of
the {\tt composite} (either by child creation or reparenting). This
method  adds the {\tt child} to the {\tt children} list and implements
the result of the insertion on the order of the {\tt children} list. 
}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
{\tt composite} contacts may have various ways of ordering their
children, usually for geometry management purposes. For example, a
{\tt composite} containing a set of command buttons may want to sort the
buttons in alphabetical order or to group them by function. A contact
programmer may redefine the {\tt add-child} method to implement the
required ordering. The primary method for {\tt add-child} simply
appends the new child to the end of the  {\tt children} list.

The lambda list for this generic function includes {\tt \&key} so that contact
programmers can define methods with additional keyword arguments.
}\end{flushright}


{\large {\bf delete-child \hfill Method, composite}}
\index{composite, delete-child method}
\index{delete-child method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & delete-child & \\
& ((composite  &composite)\\
& child\\
& \&key))
\end{tabular}
\rm

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Called automatically when the {\tt child} contact leaves the {\tt
children} list of the {\tt composite} (either by child destruction or
reparenting). This method  removes the {\tt child} from the {\tt
children} list and implements the result of the deletion on the order and
geometry of the {\tt children} list.

The lambda list for this generic function includes {\tt \&key} so that contact
programmers can define methods with additional keyword arguments.
}\end{flushright}

{\samepage
{\large {\bf (setf contact-parent) \hfill Method, contact}}
\index{contact, contact-parent method}
\index{contact-parent method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & (setf contact-parent) & \\
& (new-parent\\
&  (contact  &contact)\\
&  \&key & x y) \\
(declare &(values & composite)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
``Reparents''\index{contact, reparenting} the {\tt contact} by making it
a child of the {\tt new-parent}. {\tt x} and {\tt y} give 
the position of the {\tt contact} with respect to the origin of its {\tt
new-parent}; if omitted, then the {\tt contact}'s relative position is
unchanged. 

}\end{flushright}



\SAMEL{Geometry Management}{ch:geometry-management}
\index{geometry management}
A composite is expected to act as the {\bf geometry manager}\index{geometry manager}
for its child contacts; that is, to control
the geometrical properties of its children. As a geometry manager, the role of composite
is to
implement a style of layout for its children. In general, a
composite may operate on a contact's window without any knowledge of the class
or function of the contact. However, some composite contacts will make use of
specific knowledge about their children in order to perform geometry management.

Placing geometry control in the hands of a geometry manager in this way
has several advantages.
\begin{itemize}
\item   A geometry manager can arbitrate the competing geometry change requests
        of several contacts in order to implement contraints among them.
        
\item   A given layout style can be applied to any collection of contacts.
        
\item   Contact layout style can be changed without the knowledge of individual
        contacts.
\end{itemize}


A request to change the geometry of a contact is forwarded to the contact's
parent, which actually performs the resulting change.  It is important to
understand that, due to its constraints, a geometry manager may not be able to
perform a change as requested.  For
example, a request to increase the size of a contact might be refused if its
geometry manager enforces a maximum size.  If a requested change cannot
be done, a geometry manager should suggest a slightly different change
which would be acceptable. Frequently,
a geometry manager will want a child to compute a suitable geometry for
itself; this can be done by calling the {\tt preferred-size} function.
\index{preferred-size method}

A composite's geometry management policy applies only to the set of its children
which are managed.
\index{managed}\index{contact, managed}
Any child whose {\tt state} is {\tt :withdrawn} is ignored by a geometry manager. Any
geometry change to a {\tt :withdrawn} child is performed immediately as
requested.  

Geometry management is implemented by the following methods of the
{\tt composite} class.

{\samepage
{\large {\bf manage-geometry \hfill Method, composite}}
\index{composite, manage-geometry method}
\index{manage-geometry method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & manage-geometry & \\
& ((composite  &composite)\\
& contact\\
& x & \\
& y   \\
& width & \\
& height   \\
&border-width\\
& \&key) \\
(declare &(values &success-p \\
&&x \\
&&y \\
&& width \\
&& height \\
&& border-width)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} 
\parbox[t]{6.125in}{
Called by {\tt change-geometry}
\index{change-geometry function} 
to change the geometry of the
{\tt contact}.
If the requested change is approved, then  the first value returned is
non-{\tt nil}; the remaining return values then give the new geometry of the {\tt
contact}.  Otherwise, the change is not approved and the first value returned is
{\tt nil}; in this case, the remaining return values suggest an acceptable
compromise geometry.
If only {\tt nil} is returned, no geometry change is allowed.
}

\parbox[t]{6.125in}{
Any of the {\tt x}, {\tt y}, {\tt width}, {\tt height}, or {\tt border-width}
arguments may be {\tt nil}, indicating a ``don't care'' value for the requested
change. A geometry manager may also interpret a {\tt nil} value to mean ``just
use the current value.''
Note: {\tt manage-geometry} should never approve the request if the {\tt width}
or {\tt height} is {\tt 0}. Such a value is invalid and represents an
``uninitialized'' condition, for which {\tt manage-geometry} must suggest
an alternative.
}

\parbox[t]{6.125in}{
The lambda list for this generic function includes {\tt \&key} so that contact
programmers can define methods with additional keyword arguments.
}
\end{flushright}
 
{\samepage
{\large {\bf manage-priority \hfill Method, composite}}
\index{composite, manage-priority method}
\index{manage-priority method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & manage-priority & \\
& ((composite  &composite)\\
& contact\\
& priority & ;(member :above :below :top-if :bottom-if :opposite)\\
& sibling\\
& \&key) \\
(declare &(values &success-p\\
& & priority\\
& & sibling)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Called by {\tt change-priority}
\index{change-priority function} 
to change the stacking priority of the {\tt contact}.
See the CLX function {\tt xlib:window-priority} for a description of the {\tt
priority} and {\tt sibling} arguments.
If the
requested change is approved, then the first value returned
is non-{\tt nil}.  Otherwise, the change is not approved and the first  value returned is
{\tt nil}; in this case, the remaining return values suggest an acceptable
compromise request.
If only {\tt nil} is returned, no geometry change is allowed.

Either of the {\tt priority} or {\tt sibling} 
arguments may be {\tt nil}, indicating a ``don't care'' value for the requested
change. A geometry manager may also interpret a {\tt nil} value to mean ``just
use the current value.''


The lambda list for this generic function includes {\tt \&key} so that contact
programmers can define methods with additional keyword arguments.
}\end{flushright}

{\samepage
{\large {\bf change-layout \hfill Method, composite}}
\index{composite, change-layout method}
\index{change-layout method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & change-layout & \\
& ((composite  &composite) \\
&  \&optional & newly-managed))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Called whenever the set of managed children of the {\tt composite} changes. This
method is expected to make any changes to the geometry or priority of the new
managed set which are required by the {\tt composite}'s geometry management
policy. 

{\tt change-layout} is called once when a new composite is realized. After a
composite is realized, {\tt change-layout} is called whenever a managed child is
created or destroyed or in response to a change in the {\tt state} of a child.
When a new managed child is created, it is given as the value of the optional
{\tt newly-managed} argument. Certain geometry managers may choose to treat a
{\tt newly-managed} child specially when enforcing geometry constraints among
its managed children.

The primary {\tt change-layout} method simply calls {\tt
(change-geometry child :accept-p t)} to validate the current geometry of each
managed {\tt child}.

}\end{flushright}


The initial geometry of a contact is also determined by the geometry management
policy of it parent composite.  Just before a composite is realized, the {\tt
initialize-geometry} function is called to negotiate the initial geometry of all
descendants of a composite.  This function is called automatically by {\tt
update-state}\index{update-state function}
and rarely needs to be invoked directly by application programmers
or contact programmers.  In some cases, a CLUE program may call {\tt
initialize-geometry} in order to complete initial geometry management without
realizing a composite.

{\samepage
{\large {\bf initialize-geometry \hfill Method, composite}}
\index{composite, initialize-geometry method}
\index{initialize-geometry method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & initialize-geometry & \\
           & ((composite  composite)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Computes the initial geometry for the {\tt composite} and all of its
descendants. {\tt initialize-geometry} is called recursively for each composite
child that
is both managed and unrealized. Then, {\tt change-layout} is called to arrange
all children according to the geometry management policy of the {\tt composite}.

}\end{flushright}

 
{\samepage
\SAMEL{Focus Management}{ch:focus-management}
\index{input, focus}
A single child, which is contained in the
composite {\tt focus} slot, is usually designated to serve as the current
``keyboard representative'' for the composite. 
A composite provides a method for switching the keyboard input focus
between
the contacts in its {\tt children} list. In general, this method calls the
{\tt accept-focus-p}\index{accept-focus-p method}
method of a child contact before setting it as the keyboard
input focus.\index{accept-focus-p method}
}

{\samepage
{\large {\bf move-focus \hfill Method, composite}}
\index{composite, move-focus method}
\index{move-focus method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & move-focus \\
           & ((composite & composite)\\
           & \&optional & (direction :next) \\
           & \&key           & start\\
           & & revert-to))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
\index{input, focus}
Switches the keyboard input focus to a different child contact and returns the new focus
contact. The new focus contact is stored in the composite {\tt focus} slot.
The new focus contact is determined by the {\tt direction} and the {\tt start}
contact. The value of {\tt direction} is either {\tt :next}, {\tt :previous}, or
{\tt :set}. If {\tt direction} is {\tt :set}, then the new focus contact becomes
{\tt start}. If {\tt direction} is {\tt :next} or {\tt :previous}, it determines
the direction to search in the {\tt children} list, starting with
the {\tt start} child. 

If {\tt start} is not given, then the current {\tt focus}
child is used as the default starting point.

The {\tt revert-to} argument is used in a call to {\tt xlib:set-input-focus} and
determines the contact to which the input focus will revert in the event that
the focus contact becomes unviewable.

The primary {\tt move-focus} method considers each child, starting with
the child adjacent to {\tt start}
in the given {\tt direction}. The first child for which {\tt (accept-focus-p
child)} is non-{\tt nil} is then returned.

}\end{flushright}





\SAMEL{Roots}{ch:roots}
All of the contacts belonging to a {\tt contact-display} form a set of
hierarchies. The root of each hierarchy is a special type of composite contact
referred to as a {\bf root}\index{root}.


{\samepage
{\large {\bf root \hfill Class}} 
\index{classes, root}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defcontact & root  & \\ 
& (composite) & \\
&((screen & :type xlib:screen\\ 
&          & :initarg :screen)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
{\tt screen}
\begin{quote}
The {\tt xlib:screen} object represented by the {\tt root}.
\end{quote}

}\end{flushright}



All of the contacts descended from a {\tt root} appear on the same screen of
the {\tt contact-display}. A {\tt root} represents a display screen in
two ways. First, a {\tt root} typically corresponds to the root window of the
screen and inherits all of its properties\footnotemark\footnotetext{In some environments,
a window manager may establish a non-root window as the top-level ``parent
window'', in which case the {\tt root} will correspond to the ``parent
window'' instead.}.  
Input received by a root window
will be dispatched to its {\tt root} contact. Second, the  {\tt xlib:screen} object
may be accessed as a slot of the {\tt root}.

The set of {\tt root} objects belonging to a {\tt contact-display} is
created
automatically when the {\tt contact-display} itself is created, and is never
subsequently modified. Each {\tt contact-display} has a default root which may
be used as the default parent of newly-created contacts (see
{\tt make-contact}, Section~\ref{ch:creation}).
\index{root, default}\index{contact-display, default root}
The default
root is typically determined by the {\tt :default-screen} argument to
{\tt open-contact-display}\index{open-contact-display function}.
Alternatively, the default root may be inquired or modified using the
{\tt display-root} function.

{\samepage
{\large {\bf display-root \hfill Function, contact-display}}
\index{contact-display, display-root function}
\index{display-root function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & display-root & \\ 
& (contact-display\\
& \&optional &  screen-index) \\
(declare &(values  & root)))
\end{tabular}
\rm

}\end{flushright}
}

\begin{flushright} \parbox[t]{6.125in}{
Returns the  {\tt root} of the {\tt contact-display} specified by the
{\tt screen-index}.  If no {\tt screen-index} is given, then the default
root is returned. Used
with {\tt setf}, this function is also an accessor for
changing the default root. Example: {\tt (setf (display-root  
contact-display) (display-root contact-display 2))}.
\index{root, default}\index{contact-display, default root}

}\end{flushright}

{\samepage
{\large {\bf display-root-list \hfill Function, contact-display}}
\index{contact-display, display-root-list function}
\index{display-root-list function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & display-root-list & \\ 
& (contact-display) \\
(declare &(values  & root-list)))
\end{tabular}
\rm

}\end{flushright}
}

\begin{flushright} \parbox[t]{6.125in}{
Returns a list of all {\tt root} contacts belonging to the {\tt contact-display}.
}\end{flushright}


{\samepage
{\large {\bf contact-root \hfill Function, contact}}
\index{contact, contact-root function}
\index{contact-root function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & contact-root & \\ 
& (contact) \\
(declare &(values  & root)))
\end{tabular}
\rm

Returns the {\tt root} to which the {\tt contact} belongs. 
}\end{flushright}}

{\samepage
{\large {\bf contact-screen \hfill Function, contact}}
\index{contact, contact-screen function}
\index{contact-screen function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & contact-screen & \\ 
& (contact) \\
(declare &(values  & screen)))
\end{tabular}
\rm

Returns the {\tt xlib:screen} object associated with {\tt
(contact-root contact)}. 
}\end{flushright}}



Many applications will neither be aware of {\tt root}s nor need  to
operate on them. This is particularly true in the common case where the display
has only one screen.
However, the following operations on a {\tt root}
may be useful to an application programmer.\index{root, use by
an application} 
\begin{itemize}
\item Specify a {\tt root} as the parent of another contact in order
to create a ``top-level''\index{contact, top-level} contact on a specific display screen.
\item Define actions and event translations for a {\tt root}
\footnotemark\footnotetext{However, it is generally bad practice to attach
application meaning to root window input events, since these are often reserved
for window managers.}.  
\end{itemize}

The {\tt root} class is a subclass of the basic {\tt
composite} class,
but {\tt root}s are different from ordinary composites in several ways.
\index{root, special features}
\begin{itemize}
\item The parent of a {\tt root} is {\tt nil}.
\item The geometrical attributes of a {\tt root} cannot be changed.
\item A {\tt root} is always created automatically when its
{\tt contact-display} is created. A {\tt root} is never created by an
application.  \item The {\tt name} of a {\tt root} is
initialized automatically when it is created.  The initial resource name is {\tt
:SCREEN-}{\em n}, where {\em n} is the index of the
{\tt xlib:screen} object in {\tt (xlib:display-roots
contact-display)}~\footnotemark\footnotetext{n $\equiv$ \tt (position screen
(xlib:display-roots contact-display) :test \#'eq)}.
\item A {\tt root} composite imposes no geometry management policy.
\end{itemize}



\SAMEL{Shells}{ch:shells}

A contact whose parent is a root is called a {\bf
top-level}\index{contact, top-level} contact.  A top-level contact is usually
a composite at the top of a hierarchy
of other contacts created by an application program.  A CLUE application program
will
normally create at least one top-level contact which encapsulates user
interaction for the application.  More complex applications will often use multiple
top-level contacts, each representing distinct user tasks.  Top-level contacts
play a special role in a user interface, because only top-level windows are
subject to a user's operations for window management (performed via a window
manager client) and for session management (performed via a session manager
client).  Window managers, session managers, and the conventions for
intercommunication among these clients are described in \cite{icccm}.
\index{window manager}\index{session manager}

In addition, a top-level contact is often used as a {\bf pop-up}\index{pop-up}
--- for example, a menu which ``pops up'' when a command button contact is
``pressed.'' A top-level pop-up ``belongs'' to another contact without being
constrained by it in position, size, or stacking order.  A top-level contact
therefore has both a parent, which is always a root, and an {\bf
owner}\index{owner}\index{shell, owner}, from which it may inherit resources
values and other properties.

In order to simplify top-level contact programming, CLUE defines a composite
subclass called {\bf shells}\index{shell}.  A shell is a top-level contact which
merely acts as an invisible ``container'' for exactly one child.  From an
application programmer's point of view, the child of a shell is really the
effective top-level contact.  Programmer changes to the size of the child are
automatically applied to the shell, and user changes to the size of a shell are
automatically applied to its child.  The slots of a shell instance contain
values which form the window properties used to communicate with window managers
and session managers.  See \cite{icccm} for a complete discussion of the
conventions for client window properties.\index{property, for interclient
communication}\index{interclient communication}

Application programmers rarely need to operate on shells, other than to access
their property slots and change their state.  In return, shells encapsulate the
responsibilities required of top-level windows and conveniently integrate
top-level pop-up's into the resource name hierarchy.  All top-level contacts
should be shells; although this is not strictly required, the behavior of
non-shell top-level contacts is not guaranteed to be correct.

\pagebreak
{\samepage 
{\large {\bf shell \hfill Class}} 
\index{shell}
\index{classes, shell}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defcontact & shell  & \\ 
& (composite) & \\
& ((state     &  :type (member :withdrawn :iconic :mapped)\\
&	      &  :accessor contact-state) \\  
&  (owner     &  :type     composite\\
&	      & :reader   shell-owner))\\
(:resources & state))

\end{tabular}
\rm

}\end{flushright}}

Different CLUE shell subclasses are used to implement four basic types
of interaction with window managers and session managers:

\begin{itemize}
\item {\tt override-shell}
\item {\tt transient-shell}
\item {\tt top-level-shell}
\item {\tt top-level-session}
\end{itemize}



\LOWER{Creating A Shell}

A {\tt shell} is a {\tt composite} that has an owner.
When a shell is created, the {\tt :parent} argument to {\tt
make-contact}\index{make-contact functions} defines its owner.  The relationship
between a shell and its
owner is similar to the one between a child and its parent in the
following ways.

\begin{enumerate}
\item When an owner is destroyed, its shells are also destroyed.
\item The complete resource name/class of a shell contains the name/class
	   of its owner (instead of the name/class of its parent).
\end{enumerate}

However, an owner does not provide geometry management for its shells, and a
shell is unaffected by changes to the {\tt contact-state} and sensitivity
of its owner.

When a {\tt shell} is created, if the {\tt :parent} argument to
{\tt make-contact} is a {\tt contact-display}, then:

\begin{center}
\begin{tabular}{lll}
{\tt (contact-parent shell)} & =  & {\tt (shell-owner shell)}\\
                             & =  &{\tt (display-root parent screen)}\\
\end{tabular} \end{center}

If the {\tt :parent} argument is a contact, then:

\begin{center}
\begin{tabular}{lll}
{\tt (contact-parent shell)} & =  & {\tt (contact-root parent)}\\
{\tt (shell-owner shell)}    & =  & {\tt parent}\\ 
\end{tabular} \end{center}

A shell whose parent and owner are identical is called a {\bf root
shell}.\index{root shell}\index{shell, root} The default state of a root
shell is {\tt :mapped}.  Otherwise, the default state of a shell is {\tt
:withdrawn}.  These defaults are convenient in the typical case of an
application with a single root shell and one or more pop-up
shells.\index{shell, default state}


\SAME{Shell State}
\index{shell, state}\index{interclient communication}
The possible values for the {\tt contact-state} of a shell
differ slightly from those of ordinary contacts. Because the parent of a
shell is always a {\tt root}, a shell does not have a geometry manager
in the usual sense. Instead, a window manager client\index{window
manager} will typically allow the  user to define control the geometry
of shells and other top-level windows interactively. Shell states,
therefore, correspond to the top-level window states defined in
\cite{icccm}:

\begin{center}
\begin{tabular}{lp{3.5in}}
{\tt :withdrawn} & The shell is invisible and unavailable for input.\\
\\ 
{\tt :iconic} & Same as {\tt :withdrawn}, except that the window manager
may display an alternate visual representation of the shell (for
example, an icon). The exact nature (and even the existence) of this
alternate representation depends on the window manager.\\
\\ {\tt :mapped} & The shell is in its ``normal'' state --- mapped and
available for input.\\ \\ 
\end{tabular} \end{center}


Mapping (or ``popping up'') a shell means setting its state to {\tt
:mapped}.\index{shell, popping up}  Unmapping
(or ``popping down'')\index{shell, popping down} a shell means setting
its state to {\tt :iconic} or {\tt :withdrawn}.
Mapping a shell causes its {\tt :map} callback to be invoked.
Similarly, unmapping a shell invokes its {\tt :unmap} callback.  These
callbacks allow the application programmer to change the contents of a
shell before it is mapped or after it is unmapped.  The required
argument list for each of these callbacks is shown below.

{\samepage
{\large {\bf :map \hfill Callback, shell}} 
\index{shell, :map callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & map-function & ())
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked before the state of a {\tt shell} becomes {\tt :mapped}.

}\end{flushright}


{\samepage
{\large {\bf :unmap \hfill Callback, shell}} 
\index{shell, :unmap callback}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & unmap-function & ())
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Invoked after the state of a {\tt shell} is changed from {\tt :mapped}.

}\end{flushright}


\SAME{Shell Geometry Management}
\index{shell, geometry management}
The single child of a shell is referred to as its {\bf content}\index{shell,
content}. The basic geometry management policy implemented by the {\tt shell}
class constrains a shell and its content to have the same width and height;
size changes to one are automatically applied to the other. Certain aspects of
content geometry --- position, border width, and priority --- are fixed or irrelevant;
changes to these should be applied to the shell instead.
        
\begin{itemize}
\item {\bf Changing the width/height of a shell} causes the width/height of its
content to be changed to the new size.

\item {\bf Changing the width/height of the content} causes the width/height of its
shell to be changed to the new size.

\item {\bf Changing the border width of the content} causes the content to be
repositioned with respect to its shell, so that the content border is always
invisible. Border changes should be applied to the shell instead. See the
conventions for top-level window borders in \cite{icccm}.

\item {\bf Changing the position of the content} is never approved. Change the
position of the shell to move the shell/content with respect to the root.

\item {\bf Changing the priority of the content} is meaningless and is never
approved.  Change the priority of the shell to restack the shell/content with
respect to other top-level windows.  See the conventions for top-level window
priority in \cite{icccm}.

\end{itemize}

\SAME{Override Shells}

The {\tt override-shell} class is a subclass of shells which override the window
manager.  Use {\tt override-shell} to contain pop-up menus and other temporary
objects which the user can never resize, etc.  The {\tt :iconic} state is
meaningless for an {\tt override-shell}, which therefore can never assume this
state.  Setting the state of an {\tt override-shell} to {\tt :iconic} causes it
to become {\tt :withdrawn} instead.\index{override-shell, changing state}

{\samepage 
{\large {\bf override-shell \hfill Class}} 
\index{override-shell}
\index{classes, override-shell}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defcontact &override-shell\\
&  (shell)\\
&  () \\
(:resources \\
&    (override-redirect :initform :on))) 									     
\end{tabular}
\rm
}\end{flushright}}




\SAME{Window Manager Shells}

The {\tt wm-shell} class is a subclass of shells which interact with the
window manager.  The accessors defined by the {\tt wm-shell} class allow
the application programmer to initialize and modify the standard
top-level window properties used to communicate with the window
manager.\index{window manager} See \cite{icccm}, Section 4.1.2.
\index{property, for interclient communication}
\index{interclient communication}
{\tt wm-shell} should not be instantiated directly.  Instead, window
manager shells are always instances of one of the {\tt wm-shell}
subclasses --- {\tt transient-shell} or {\tt top-level-shell}.
\pagebreak
{\samepage 
{\large {\bf wm-shell \hfill Class}} 
\index{wm-shell}
\index{classes, wm-shell}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defcontact &wm-shell \\
& (shell) \\
& ((hints&                :type     (or null xlib:wm-hints) \\
&			& :initform nil  \\
&			& :initarg  :hints \\
&			& :accessor shell-hints)    \\
&   (normal-hints &        :type     (or null xlib:wm-size-hints) \\
&			& :initform nil  \\
&			& :initarg  :normal-hints \\
&			& :accessor shell-normal-hints) \\
&   (protocols &           :type     (or null list)  \\
&			& :initform nil  \\
&			& :initarg  :protocols \\
&			& :accessor wm-protocols) \\
&   (title   &             :type     (or null xlib:stringable) \\
&			& :initform nil  \\
&			& :initarg  :wm-title \\
&			& :accessor wm-title)))
\end{tabular}
\rm
}\end{flushright}}


\begin{flushright} \parbox[t]{6.125in}{
{\tt hints}
\begin{quote}
An {\tt xlib:wm-hints} structure which defines the value of the
{\tt :wm\_hints} property of a {\tt wm-shell}.\index{shell, hints
property}\index{property, hints} 
\end{quote}

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
{\tt normal-hints}
\begin{quote}
An {\tt xlib:wm-normal-size} structure which defines the value of the
{\tt :wm\_normal\_hints} property of a {\tt wm-shell}.\index{shell,
normal hints property}\index{property, normal hints} 
\end{quote}
}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
{\tt protocols}
\begin{quote}
A list of atom keywords which defines the value of the
{\tt :wm\_protocols} property of a {\tt wm-shell}.
\index{wm-protocols method}
\index{shell, protocols
property}\index{property, protocols} 
\end{quote}

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
{\tt title   }
\begin{quote}
A string which defines the value of the
{\tt :wm\_name} property of a {\tt wm-shell}.\index{shell, name
property}\index{property, name} 
\end{quote}

}\end{flushright}


The {\tt transient-shell} class is
a subclass of shells which are {\bf transients}\index{shell, transients}
for
their owners. The exact meaning of this relationship is defined by the
window manager, but typically a window manager will unmap a {\tt
transient-shell} when its owner becomes unmapped or iconified and will
not allow a {\tt transient-shell} to be individually iconified.  A window
manager may also display a {\tt transient-shell} with distinctive
``decoration.''

{\samepage 
{\large {\bf transient-shell \hfill Class}} 
\index{transient-shell}
\index{classes, transient-shell}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defcontact &transient-shell \\
& (wm-shell)\\
&  ())
\end{tabular}
\rm

}\end{flushright}}
 

The {\tt top-level-shell} class is the base class of normal top-level
shells, with full window manager interaction.  A root shell is typically
a {\tt top-level-shell}.\index{shell, root}

{\samepage 
{\large {\bf top-level-shell \hfill Class}} 
\index{top-level-shell}
\index{classes, top-level-shell}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defcontact & top-level-shell \\
&  (wm-shell) \\
&  ((colormap-owners   & :type     list \\
&		       & :initform nil  \\
&		       & :initarg  :colormap-owners \\
&		       & :accessor wm-colormap-owners)    \\
&   (icon              & :type     (or null xlib:drawable) \\
&		       & :initform nil  \\
&		       & :initarg  :icon \\
&		       & :accessor wm-icon)    \\
&   (icon-mask         & :type     (or null xlib:pixmap) \\
&		       & :initform nil  \\
&		       & :initarg  :icon-mask \\
&		       & :accessor wm-icon-mask)    \\
&   (icon-title        & :type     (or null xlib:stringable) \\
&		       & :initform nil  \\
&		       & :initarg  :icon-title \\
&		       & :accessor wm-icon-title)    \\
&   (icon-x            & :type     (or null xlib:int16) \\
&		       & :initform nil  \\
&		       & :initarg  :icon-x \\
&		       & :accessor wm-icon-x)    \\
&   (icon-y            & :type     (or null xlib:int16) \\
&		       & :initform nil  \\
&		       & :initarg  :icon-y \\
&		       & :accessor wm-icon-y)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
{\tt colormap-owners}
\begin{quote}
A list of contacts which defines the value of the
{\tt :wm\_colormap\_windows} property of a {\tt
top-level-shell}.\index{top-level-shell, colormap windows
property}\index{property, colormap windows} 
\end{quote}

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
{\tt icon}
\begin{quote}
An {\tt xlib:drawable} which defines the icon window/pixmap slot in the
{\tt :wm\_hints} property of a {\tt top-level-shell}.\index{top-level-shell, hints
property}\index{property, hints} 
\end{quote}

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
{\tt icon-mask}
\begin{quote}
An {\tt xlib:pixmap} which defines the icon mask slot in the
{\tt :wm\_hints} property of a {\tt top-level-shell}.\index{top-level-shell, hints
property}\index{property, hints} 

\end{quote}

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
{\tt icon-title}
\begin{quote}
A string which defines the value of the
{\tt :wm\_icon\_name} property of a {\tt
top-level-shell}.\index{top-level-shell, icon name
property}\index{property, icon name} 
\end{quote}

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
{\tt icon-x}, {\tt icon-y}
\begin{quote}
Define the icon position slots in the
{\tt :wm\_hints} property of a {\tt top-level-shell}.\index{top-level-shell, hints
property}\index{property, hints} 
\end{quote}

}\end{flushright}



\SAME{Top-Level Sessions}
A {\tt top-level-session} is a special kind of {\tt top-level-shell} used
to communicate with a session manager.\index{session manager} 
According
to standard interclient communication conventions\cite{icccm}, an
application should create at least one ``main window'' which is a
{\tt top-level-session}; typical applications use only one {\tt
top-level-session}.
The accessors defined by the {\tt top-level-session} class allow
the application programmer to initialize and modify the standard
top-level window properties used to communicate with the window
manager.\index{session manager} See \cite{icccm}, Section 5.1.1.
\index{property, for interclient communication}
\index{interclient communication}

{\samepage 
{\large {\bf top-level-session \hfill Class}} 
\index{top-level-session}
\index{classes, top-level-session}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defcontact & top-level-session \\
& (top-level-shell) \\
&  ((client-host       & :type     (or null xlib:stringable) \\
&		       & :initform nil  \\
&		       & :initarg  :client-host \\
&		       & :accessor sm-client-host) \\
&   (command           & :type     (or null string) \\
&		       & :initform nil  \\
&		       & :initarg  :command \\
&		       & :accessor sm-command)))
\end{tabular}
\rm

}\end{flushright}
}

\begin{flushright} \parbox[t]{6.125in}{
{\tt client-host}
\begin{quote}
A string which defines the value of the
{\tt :wm\_client\_machine} property of a {\tt
top-level-session}.\index{top-level-session, client machine
property}\index{property, client machine} 
\end{quote}
}\end{flushright}


\begin{flushright} \parbox[t]{6.125in}{
{\tt command}
\begin{quote}
A string which defines the value of the
{\tt :wm\_command} property of a {\tt top-level-session}.\index{top-level-session, command
property}\index{property, command} 
\end{quote}
}\end{flushright}



\SAME{Changing Shell Properties}

An application programmer controls the way {\tt transient-shell}, {\tt
top-level-shell}, and {\tt top-level-session} objects interact with the
window manager and the session manager by using accessors defined by
these classes to change slot values.  In general the effect of using
such an accessor is to send a {\tt :change-property} request which modifies one
of the standard window properties used for interclient
communication.\index{property, for interclient communication} 
The {\tt
with-wm-properties} macro allows more efficient server communication by
batching multiple changes to a shell property into a single
{\tt :change-property} request.

{\samepage
{\large {\bf with-wm-properties \hfill Macro}} 
\index{with-wm-properties macro}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmacro & with-wm-properties & \\ 
& ((shell)\\
& \&body body))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
The given {\tt shell} may be a {\tt transient-shell}, a {\tt
top-level-shell}, or a {\tt top-level-session}. Changes to {\tt shell}
slots made within the dynamic extent of the {\tt body} do not
immediately cause {\tt :change-property} requests to be sent. Instead, a single
{\tt :change-property} request for each modified {\tt shell} property is sent
after the {\tt body} is executed.

}\end{flushright}

\SAME{Interclient Messages}\index{interclient communication} 
Application
programs may communicate with other clients, such as the window manager and the
session manager \index{window manager}\index{session manager} using standard
protocols selected by the {\tt wm-protocols}\index{wm-protocols method}
accessor.  See \cite{icccm} for a description of the standard protocols for
interclient communication.  These protocols involve {\tt :client-message} events
which are sent by the window/session manager to an application {\tt shell}.  The
{\tt wm-message} structure defines accessor functions which may be used to
interpret the
{\tt data} found in any standard {\tt :client-message} event sent by the
window/session manager.

{\samepage
{\large {\bf wm-message \hfill Structure}} 
\index{wm-message structure}
\begin{flushright} 
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
(defstruct & (wm-message (:type (vector int32))) \\
           & protocol \\
           & timestamp)\\
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Defines the common data fields of all standard {\tt :client-message} events from
a window/session manager mgr. The {\tt protocol} slot is 
the resource id number ({\tt xlib:card29}) for the {\tt xlib:xatom} which
identifies the
standard message type. The {\tt timestamp} slot is an {\tt xlib:timestamp}
identifying the time when the message was sent.

}\end{flushright}



CLUE defines the following special event specifications \index{event
specification, interclient messages} in order to simplify processing
of {\tt :client-message} events sent by the window/session manager to an
application {\tt shell}.

{\samepage
\index{wm\_delete\_window message}
{\tt (:wm\_delete\_window {\em accessor-value}*)}\\
\hspace*{.75in}
\parbox[t]{5.75in}{
\begin{tabbing}
{\em accessor-value} \= ::= \= \kill
{\em accessor-value} \>::= \>{\em function} {\em value} \\
\end{tabbing}}
}
\begin{flushright}
\parbox[t]{5.75in}{
This
form of event specification matches a {\tt :client-message}
event when it is a {\tt :wm\_delete\_window} message from the session manager.
If
any accessor function/value pairs are
given, then the {\tt data} slot of the event must
match each function/value. That is, {\tt (equal (funcall {\em function}
data) {\em value})} must be true for each {\em accessor-value}.
During accessor matching, the special variable {\tt *event-display*} is
bound to the {\tt display} slot of the event. The event display may be
needed to convert X resource id numbers in the {\tt data} into the form
used in CLX and CLUE.}

\parbox[t]{5.75in}{
This message may be received by a {\tt top-level-shell} which has selected the 
{\tt :wm\_delete\_window} protocol. This message indicates that the user has
requested that the {\tt top-level-shell} be destroyed.}
\end{flushright}

{\samepage
\index{wm\_save\_yourself message}
{\tt (:wm\_save\_yourself {\em accessor-value}*)}\\
\hspace*{.75in}
\parbox[t]{5.75in}{
\begin{tabbing}
{\em accessor-value} \= ::= \= \kill
{\em accessor-value} \>::= \>{\em function} {\em value} \\
\end{tabbing}}
}
\begin{flushright}
\parbox[t]{5.75in}{
This
form of event specification matches a {\tt :client-message}
event when it is a {\tt :wm\_save\_yourself} message from the session manager.
If
any accessor function/value pairs are
given, then the {\tt data} slot of the event must
match each function/value. That is, {\tt (equal (funcall {\em function}
data) {\em value})} must be true for each {\em accessor-value}.
During accessor matching, the special variable {\tt *event-display*} is
bound to the {\tt display} slot of the event. The event display may be
needed to convert X resource id numbers in the {\tt data} into the form
used in CLX and CLUE.}

\parbox[t]{5.75in}{
This message may be received by a {\tt top-level-session} which has selected the 
{\tt :wm\_save\_yourself} protocol. This message indicates that the application
program should save any internal data in preparation for termination by the
session manager.}
\end{flushright}


{\samepage
\index{wm\_take\_focus message}
{\tt (:wm\_take\_focus {\em accessor-value}*)}\\
\hspace*{.75in}
\parbox[t]{5.75in}{
\begin{tabbing}
{\em accessor-value} \= ::= \= \kill
{\em accessor-value} \>::= \>{\em function} {\em value} \\
\end{tabbing}}
}
\begin{flushright}
\parbox[t]{5.75in}{
\index{input, focus}
This
form of event specification matches a {\tt :client-message}
event when it is a {\tt :wm\_take\_focus} message from the window manager.
If
any accessor function/value pairs are
given, then the {\tt data} slot of the event must
match each function/value. That is, {\tt (equal (funcall {\em function}
data) {\em value})} must be true for each {\em accessor-value}.
During accessor matching, the special variable {\tt *event-display*} is
bound to the {\tt display} slot of the event. The event display may be
needed to convert X resource id numbers in the {\tt data} into the form
used in CLX and CLUE.}

\parbox[t]{5.75in}{
This message may be received by a {\tt top-level-shell} which has selected the 
{\tt :wm\_take\_focus} protocol. This message indicates that the user wants to make
the {\tt top-level-shell} (or one of its descendants) the focus for keyboard input.}

\parbox[t]{5.75in}{
CLUE defines a default {\tt wm-shell} class event translation for {\tt
:wm\_take\_focus} that automaticallly sets the input focus to the contact which
is the content of the receiving shell\index{shell, content}
(using {\tt accept-focus-p}).\index{accept-focus-p method}
If the content is a {\tt composite} and {\tt (not (accept-focus-p content))},
then {\tt move-focus}\index{move-focus method} is used to set the focus to its
{\tt composite-focus} child.
}\end{flushright}

\HIGHER{Hierarchy Utility Functions}
The following functions are useful for manipulating the contact
hierarchy.

{\samepage
{\large {\bf ancestor-p \hfill Function, contact}} 
\index{ancestor-p function}
\index{contact, ancestor-p function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & ancestor-p & \\ 
& (contact\\
&  composite) \\
(declare &(values  & boolean)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns non-{\tt nil} if {\tt composite} is an ancestor of {\tt contact}.

}\end{flushright}

{\samepage
{\large {\bf next-sibling \hfill Function, contact}} 
\index{next-sibling function}
\index{contact, next-sibling function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & next-sibling & \\ 
& (contact) \\
(declare &(values  & contact)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns the next contact in the {\tt children} list of {(\tt contact-parent
contact)} following {\tt contact} (or {\tt nil}, if {\tt contact} is the last
element of the list).

}\end{flushright}

{\samepage
{\large {\bf previous-sibling \hfill Function, contact}} 
\index{previous-sibling function}
\index{contact, previous-sibling function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & previous-sibling & \\ 
& (contact) \\
(declare &(values  & contact)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns the next contact in the {\tt children} list of {(\tt contact-parent
contact)} preceding {\tt contact} (or {\tt nil}, if {\tt contact} is the first
element of the list).

}\end{flushright}


{\samepage
{\large {\bf top-level-p \hfill Function, contact}} 
\index{top-level-p function}
\index{contact, top-level-p function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & top-level-p & \\ 
& (contact) \\
(declare &(values  & boolean)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns non-{\tt nil} if the parent of {\tt contact} is a {\tt root}.

}\end{flushright}

\CHAPTERL{Graphics Contexts}{ch:gcontexts}

\index{gcontext}
Clients of the X Window System\index{X Window System, graphics context}
specify the visual attributes of graphical output primitives by using
{\bf graphics contexts}.\index{graphics context}
A graphics context is a set of graphical attribute values (e.g.
foreground color, font, line style, ``raster-op'' function, etc.) which
is created and maintained by the X server at the request of a client
program. The client program, which may use several different graphics
contexts at different times, is responsible for specifying which
graphics context is used with each graphical output request. See
\cite{x-protocol} for a complete treatment of the use of graphics
contexts in the X Window System. CLX\cite{clx} represents a graphics context by an
object of type {\tt xlib:gcontext} and also defines a simple caching
scheme which expedites the modification and inquiry of {\tt
xlib:gcontext} attributes.
CLUE provides support for more efficient sharing of graphics context
objects among several components of the user interface.  Contact
programmers are still free to adopt various policies for sharing
graphics contexts, including hierarchical inheritance or no sharing at
all.

\LOWER{Using the Graphics Context Cache}
The CLUE macro {\tt using-gcontext} allows the programmer transparent
access to a cache of previously-created {\tt xlib:gcontext} objects. As
a consequence of the {\tt using-gcontext} macro, most CLUE programmers
will seldom need to explicitly create or free graphics contexts. 
The caching strategy implemented by {\tt using-gcontext} is intended to
minimize the number of {\tt xlib:gcontext} objects created. A programmer
requests a graphics context containing a specific set of attribute
values. The {\tt using-gcontext} macro creates a new {\tt xlib:gcontext}
with these attributes only if such a {\tt xlib:gcontext} is not already
present in its cache and the cache is not full. If the cache is full, then {\tt
using-gcontext} modifies a previously-cached {\tt xlib:gcontext} and returns
it.

{\samepage
{\large {\bf using-gcontext \hfill Macro}} 
\index{using-gcontext macro}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmacro & using-gcontext & \\ 
& ((gcontext \\
& \&rest & gcontext-options\\ 
& \&key  & default \\
& \&allow-other-keys)\\
& \&body  &body))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Executes the {\tt body} forms in a lexical context in which {\tt
gcontext} is bound to an {\tt xlib:gcontext} object containing the
specified attributes. {\tt gcontext-options} is a sequence of
keyword-value pairs which can include any attribute keyword accepted by
{\tt xlib:create-gcontext}.

A {\tt :drawable} argument must be given. \index{drawable} 
{\tt gcontext} can be used in
graphics operations on any {\tt xlib:drawable} with the same root and depth as
the given {\tt :drawable} argument.


The optional {\tt :default} keyword argument specifies an existing
{\tt xlib:gcontext} object which furnishes default attribute values.
Attributes in {\tt gcontext} which are not given by {\tt
gcontext-options} then have the value contained in {\tt default}.
If {\tt :default} is omitted, then default values for {\tt gcontext} are
those defined by the X Window System protocol.

The contents of {\tt gcontext} should not be modified inside the {\tt body}.
This macro replaces the use of the {\tt xlib:create-gcontext} and {\tt
xlib:free-gcontext} functions and the {\tt xlib:gcontext-} accessors.

}\end{flushright}


\SAME{Policies for Sharing Graphics Contexts}
\index{graphics context, sharing}
Different policies may be used for sharing graphics contexts among
several contacts, depending upon how graphics attribute state information is
associated with contact instances.

Typically, a contact class may define instance variables which associate
some graphics attribute state with class instances. For example,
instances of a contact class for text display might have instance
variables
which record their current font, foreground color, and background color.
Methods of this class would then generally perform graphics output
in the body of a {\tt using-gcontext} form, as shown below.

{\samepage
\begin{center}
\begin{verbatim}
(with-slots (font fg bg) self
  (using-gcontext
    (gcontext :font       font
              :foreground fg
              :background bg)
    ...
    ))
\end{verbatim}

\end{center}}

In this case, graphics output would always exhibit the associated
attributes and would use constant defaults for any other graphical
attributes.
This is an example of a ``transparent sharing'' policy, since the
programmer is not concerned with which {\tt xlib:gcontext} objects are
used.  Only one {\tt xlib:gcontext} object containing the required
attributes needs to be created, and sharing is accomplished
automatically via {\tt using-gcontext}'s cache.


\index{graphics context, hierarchical inheritance}
A ``hierarchical inheritance'' policy would allow contacts to inherit
defaults for graphical attributes from their ancestors. For example,
hierarchical inheritance would allow all children of a given composite
to appear in the same foreground/background colors by default. A
hierarchical inheritance policy requires the contact programmer to
define some
method of associating a default {\tt xlib:gcontext} with an ancestor.
Then, methods of children contacts could perform graphics output
as shown below. In the following example, a function called {\tt gcontext-from}
is used to return the inherited graphics context. Here, too, the
programmer is concerned only
with specifying the required graphical attributes and defaults, and not
with how the {\tt xlib:gcontext} is created.

\pagebreak
{\samepage
\begin{center}
\begin{verbatim}
(with-slots (parent font) self
  (using-gcontext
    (gcontext :default    (gcontext-from parent) 
              :font       font)
    ;; Foreground/background are inherited, but
    ;; font is given by child instance data.
    ...
    ))
\end{verbatim}

\end{center}}

Changes to values in the inherited default graphics context would then
affect the appearance of child contacts.
Again, in this example, the
programmer is concerned only
with specifying the required graphical attributes and defaults, and not
with how the {\tt xlib:gcontext} is created.

A contact programmer could also choose to associate a graphics context
with each instance of his classes and to perform graphics output with
this graphics context directly.

{\samepage
\begin{center}
\begin{verbatim}
(with-slots (gcontext) self
  ;; Graphics context cache is not used.
  ...
  )
\end{verbatim}

\end{center}}

In this case, {\tt xlib:create-gcontext} must be called to compute a value for the
{\tt gcontext} slot.  Any sharing of {\tt xlib:gcontext} objects among
contacts must be controlled  explicitly by the programmer, and changes to shared
graphics contexts will have side-effects.


\CHAPTERL{Resource Management}{ch:resource-management}
Users need a way to specify preferences for various values of the user interface
(e.g. colors, fonts, title strings, etc.). Applications, too, need a
consistent method
for determining the default interface values that are specific to them. It also
is useful if application interface values can be modified by a user
``externally,'' without change to the application program. For example, this
capability can make it easy to change the color scheme of a user
interface.  

In CLX, such interface values
are referred to as {\bf resources}\index{resource}. CLX defines functions for
storing and retrieving interface resources from  a {\bf resource
database}\index{resource, database}. CLUE automatically accesses contact
resources during contact initialization; the resource database used is given by
the value of the special variable {\tt *database*}.\index{*database*}\index{variables, *database*}

\LOWER{Resource Databases}
This section summarizes the features of an {\tt xlib:resource-database}.
See \cite{xlib} and \cite{clx} for a complete description of CLX resource
management.

Conceptually, a resource database is a set of resource name-value pairs (or 
{\bf resource bindings}\index{resource, binding}). Some examples of resource
bindings are shown below. In these examples, we assume that {\tt mail} is the
resource name of a mail reading application; {\tt mail} uses a contact of the
class {\tt button} whose name is {\tt reply}.

\begin{center}
\tt
\begin{tabular}{ll}
{\rm Resource Name} & {\rm Resource Value}\\
\\
(mail screen-1 reply background) & 'green\\
(mail * background)       & 'red\\
(* button background)     & 'blue
\end{tabular}
\rm
\end{center}

These resource bindings specify that the background color resource of
{\tt mail}'s {\tt reply} button has the value {\tt green} on {\tt screen-1}, that
the background color for the rest of the {\tt mail} application is always {\tt
red} on all screens, and that, in general, the background color for all {\tt button}
contacts is {\tt blue}.  Thus, the name in a resource binding is a list
of symbols (or strings) which are hierarchically related in a way that
corresponds to
a path down a parent-child tree of contacts.  The name can be a partial
(or incomplete) path, can use ``wildcarding'' for partial paths, and can include both
resource names and contact class symbols at any position.

A user can establish 
resource bindings in a resource database by using the {\tt define-resources}
macro or the {\tt xlib:add-resource} function.
The {\tt describe-resource} function may be used to print the values in a
resource database associated with a given name.
It can also be useful to process the set of resource bindings in a resource
database (for example, to save them to a file). The
{\tt xlib:map-resource} function is designed for this purpose.


{\large {\bf define-resources \hfill Macro}} 
\index{define-resources macro}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmacro & define-resources & \\ 
& (\&rest & resource-bindings))
\end{tabular}
\rm

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
Establishes values for the given resources in a resource database. 
The resource database used is given by the value of the special variable {\tt
*database*}.\index{*database*}\index{variables, *database*}
The {\tt resource-bindings} arguments form a sequence of name/value pairs.
If the resource database already contains a value for a name, then it
is replaced by the new value. Value arguments are evaluated but name
arguments are not. 
}\end{flushright}


{\large {\bf undefine-resources \hfill Macro}} 
\index{undefine-resources macro}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmacro & undefine-resources & \\ 
& (\&rest & resource-bindings))
\end{tabular}
\rm

}\end{flushright}

\begin{flushright} \parbox[t]{6.125in}{
The {\tt resource-bindings} arguments form a sequence of name/value pairs.
Any resource binding for a given name argument is removed from a resource
database. The resource database used is given by the value of the special variable {\tt
*database*}.\index{*database*}\index{variables, *database*}
The name arguments are not evaluated. Value arguments are
ignored.

}\end{flushright}


{\samepage
{\large {\bf describe-resource \hfill Function}} 
\index{describe-resource function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & describe-resource & \\ 
& (name\\
& \&optional & (database *database*)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Prints  on {\tt *standard-output*} a description of each value associated with
the {\tt name} in the given {\tt database}. Specifically, a resource binding
in the {\tt database} is printed if {\tt name} is the last element of its
resource name.

}\end{flushright}


{\samepage
{\large {\bf *database* \hfill Variable}} 
\index{*database*}\index{variables, *database*}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defvar & *database* & (make-resource-database :reversep t))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Used as the default resource database by CLUE functions.

}\end{flushright}



\SAMEL{Complete Names and Classes}{ch:complete-names}
In order to access a contact resource value in a resource database, an
application uses two items as a ``key'': a {\bf complete resource name},
\index{complete resource name}
\index{resource, complete name}
\index{resource, complete class} 
and a {\bf complete resource class}\index{complete
resource class}. A
contact's complete resource
name and class are derived from the contact and its (current) ancestors. The
complete resource name is a list of symbols of the form {\tt ({\em name$_{1}$
\ldots name$_{n-1}$  name$_{n}$})}, where {\em name$_{n}$} is the
{\tt name} of the contact, {\em name$_{n-1}$} is the {\tt name} of
the contact's {\tt parent}, etc., and {\em name$_{1}$} is the {\tt
name} of the {\tt contact-display} to which the contact belongs (see below).
Similarly, a contact's complete resource class is a list of type symbols of the form
{\tt ({\em class$_{1}$
\ldots class$_{n-1}$  class$_{n}$})}, where {\em class$_{n}$} is the
class of the contact,\footnote{The class symbol for a contact is the value
of {\tt (class-name (class-of contact))}.} 
{\em class$_{n-1}$} is the class of
the contact's {\tt parent}, etc., and {\em class$_{1}$} is the {\tt
class} of
the {\tt contact-display} to which the contact belongs \footnotemark
\footnotetext{The complete resource class should not be confused
with the inheritance classes of a contact. The complete resource class depends
on the parent-child structure of the contact hierarchy and can change at run
time. The inheritance class of the contact (its ``class precedence list'') is
fixed at compile
time.}.  Complete resource name and class lists thus have the same length. 

The names of the resources used by a contact are defined by the contact class
and are given by the resource specification list \index{resource, specification}
in a {\tt defcontact} form (see Section~\ref{ch:defcontact}). Each such contact
resource also has a complete resource name, defined to be {\tt (append
(contact-complete-name {\em contact}) (list {\em
resource-name}))}. Similarly, the complete resource
class of a contact resource is defined to be {\tt (append
(contact-complete-class {\em contact})
(list {\em resource-class}))}, where {\em resource-class} is given by the
{\tt :class} option of the resource specification.

For all contacts that belong
to a {\tt contact-display}, the ``top-level'' complete resource name component
is a resource name symbol associated with the {\tt
contact-display}. Since an application usually uses a single {\tt
contact-display}, this name is usually a symbol which identifies the
application itself.  This name is given as the value of the {\tt
:name} keyword argument to the {\tt open-contact-display} function. 
\index{open-contact-display function}
In addition,
the {\tt display-name} and {\tt display-class}
macros may be used to inquire  the name and class, respectively, of a
{\tt contact-display}.

{\samepage
{\large {\bf display-name \hfill Macro, contact-display}} 
\index{display-name macro}
\index{contact-display, display-name macro}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmacro & display-name & \\ 
& (contact-display) \\
(declare &(values  & symbol)))
\end{tabular}
\rm

}\end{flushright}}
\begin{flushright} \parbox[t]{6.125in}{
Returns the {\tt contact-display} resource name symbol.

}\end{flushright}

{\samepage
{\large {\bf display-class \hfill Macro, contact-display}} 
\index{display-class macro}
\index{contact-display, display-class macro}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmacro & display-class & \\ 
& (contact-display) \\
(declare &(values  & symbol)))
\end{tabular}
\rm

}\end{flushright}}
\begin{flushright} \parbox[t]{6.125in}{
Returns the {\tt contact-display} resource class symbol.

}\end{flushright}


\SAMEL{Representation Types}{ch:representation-types}
A representation type \index{representation type}\index{resource, representation
type} allows an application to 
request different representations of the same resource value. For example, a
color value might be represented either as a name string (``red''), a pixel
value, an RGB
triplet, an HSV triplet, etc. Only one representation for the resource value is
actually stored in a resource database. Conversion functions may be invoked
to return a representation type different from the one stored.

The representation type used for a contact resource is defined by the {\tt
:type} option of its resource specification in the {\tt defcontact}.  During
contact initialization, a contact resource value read from a resource
database by {\tt make-contact}
\index{make-contact function}
is automatically converted
to its specified representation type.

CLUE performs resource representation type conversion by calling the
{\tt convert} function.  
\index{resource, type conversion}
CLUE defines methods for the {\tt convert} function to handle all standard
conversions. 
The standard representation type conversions provided by CLUE are shown
in Figure~\ref{fig:conversions}.\index{representation type, standard
conversions}

In order
to define a new representation type, the contact programmer must define
methods for {\tt
convert} that handle the new representation type appropriately. Typically,
{\tt convert} methods will specify parameter specializers for {\tt type}
(e.g. {\tt (eql {\em data-type})}) and for {\tt value} and will be defined only
for each valid source/destination type pair. 


{\large {\bf convert \hfill Method}}
\index{contact, convert method}
\index{convert method}
\begin{flushright}
\parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & convert & \\
& (contact\\
& (value & t)\\
& (type  & t))\\
(declare &(values &new-value)))
\end{tabular}
\rm

Converts the {\tt value} into a new value whose data type is {\tt type}. If the
requested conversion cannot be performed, then {\tt nil} is returned.
 
This
method implements a type-conversion facility designed specifically for contact
resources.\index{resource, type conversion}\index{resource, representation type}
Resource type conversion requires a {\tt contact} argument because resource
representation may depend upon attributes of a display, a screen, or even the
contact itself. 

The primary method for {\tt convert} is capable of converting any {\tt
read}-able string representation of a Common Lisp data type.  When the {\tt
value} type is {\tt xlib:stringable}, this method uses {\tt read-from-string};
if the result satisfies the {\tt type,} then it is used. The primary {\tt
convert} method also handles {\tt type} specifiers of the form {\tt (or {\em
type*})} and {\tt (member {\em atom*})}.

}\end{flushright}

\begin{figure}[h]
\caption{Standard Type Conversions}
\label{fig:conversions}
\begin{center}
\tt
\begin{tabular}{|ll|} \hline
{\rm Value Type} & {\rm Result Type}\\ \hline
& \\ 
xlib:card8 & xlib:cursor\\ 
xlib:image      & xlib:pixmap \\
xlib:stringable & keyword\\ 
xlib:stringable & t\\ 
xlib:stringable & xlib:boolean \\ 
xlib:stringable & xlib:color\\ 
xlib:stringable & xlib:cursor\\ 
xlib:stringable & xlib:font \\ 
xlib:stringable & xlib:image \\ 
xlib:stringable & xlib:pixel\\ 
xlib:stringable & xlib:pixmap\\ 
t               & string \\
(float 0 1)     & xlib:pixmap \\
(rational 0 1)  & xlib:pixmap \\
\hline
\end{tabular}
\rm
\end{center}
\end{figure}


\SAMEL{Accessing Resource Values}{ch:accessing-resources}
\index{resource, accessing}
The power and flexibility of resource management are the result of the way
resource values in a resource database are accessed. A resource binding
stored in
the database generally contains only a partial resource name consisting of a
mixture of name and class symbols. To look up a
resource value, one starts with a complete resource name and a
complete resource class. The lookup algorithm then returns the value
for the resource binding whose partial name is the closest match to the complete
name and class given. The definition of ``closest match'' takes into account
the
top-down, parent-child hierarchy of resource names/classes.



The intent of the lookup  algorithm is to formalize an
intuitive notion of ``the closest match''.  
\begin{itemize} 
\item Precedence is given to a  match which begins ``higher'' in the
parent-child contact hierarchy. This allows a resource binding with a partial
name to define a resource value shared by all members of a contact subtree.

\item Precedence is given to the more specific match. A name match is more
specific than a class match. 

\item The more name/class components matched, the closer the match.
\end{itemize}

The matching of resource names may be precisely defined by the {\tt match-p}
function shown in Figure~\ref{fig:match-p}. {\tt match-p} tests if a partial
name matches a complete
name/class.  If it does, then the value returned is a numerical score
representing the closeness of the match (the greater the score, the closer the
match). Comparison of names uses a function called {\tt same-name-p}, which uses
case-insensitive comparison if either name is a symbol, but  uses
case-sensitive comparison if both names are strings.
\index{resource, matching}\index{match-p function}

\begin{figure}[hb]
\caption{Matching Resource Names}
\label{fig:match-p}
\index{match-p function}
\begin{verbatim}
(defun match-p (partial-name complete-name complete-class) 
  (declare (type   list complete-name complete-class partial-name)
           (values (OR null (integer 0))))  
  (do ((names   complete-name  (cdr names))             ;Loop through names...
       (classes complete-class (cdr classes))           ;  and classes...
       (score   0              (ash score 2))           ;  adding up the score.
       (exact-matching-p t)                             ;Start looking for exact match.
       no-exact-match)
      ((or (null partial-name)                          ;Partial name is fully-matched.
           (> (length partial-name) (length names))     ;A match is no longer possible.
           no-exact-match)                              ;...and can't match wildcard.
       (when (null partial-name) score))                ;Return score, if match.      
    (let ((name    (car names))
          (class   (car classes))
          (partial (car partial-name)))
      (when (same-name-p partial '*)
        (setq exact-matching-p nil)                     ;Now look for wildcard match.
        (pop partial-name)
        (setq partial (car partial-name)))
      (when
        (cond
          ((same-name-p name  partial) (incf score 2))  ;Name match worth 2 points. 
          ((same-name-p class partial) (incf score 1))  ;Class match worth 1 points     .        
          ((setq no-exact-match exact-matching-p) nil)) ;No match unless wildcarding.
          ; Otherwise, matching fails but we're wildcarding: just try next name/class.
                       
        (pop partial-name)
        (setq exact-matching-p t)))))                   ;Resume looking for exact match.
\end{verbatim}
\end{figure}

For example, assume that a resource database contains the 
resource bindings shown in the previous example.

\begin{center}
\tt
\begin{tabular}{ll}
{\rm Resource Name} & {\rm Resource Value}\\
\\
(mail screen-1 reply background) & 'green\\
(mail * background)       & 'red\\
(* button background)     & 'blue
\end{tabular}
\rm
\end{center}

If the {\tt mail} application's {\tt reply} button contact requests the
value for its {\tt background} resource, using the complete resource
name {\tt (mail screen-1 reply background)} and the complete resource
class  {\tt (contact-display root button fill)}, then
each of the partial names in the database ``matches.''

\begin{center}
\tt
\begin{tabular}{ll}
(match-p '(mail screen-1 reply background) \ldots) & = \ 680\\
(match-p '(mail * background) \ldots)       & = \ 520\\
(match-p '(* button background) \ldots)     & = \ 24
\end{tabular}
\rm
\end{center}

However, {\tt (mail screen-1 reply background)} is clearly the closest match and
has the highest ``score.''

The {\tt xlib:get-resource} function uses the above algorithm to look up the
resource value in a resource database which is the closest match to a given
complete resource name and class.
The most common access to resources occurs during contact initialization, using
the complete resource name and class of the contact. The {\tt resource} function
may be used to return the value of a contact resource found at  initialization. The {\tt
resource} function also returns a resource value of the correct
representation type. The {\tt default-resources} function may be used to return
the default values for contact resources.

{\samepage
{\large {\bf resource \hfill Function, contact}}
\index{contact, resource function}
\index{resource function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & resource & \\
& (contact\\
& resource-name) \\
(declare &(values &resource-value)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns the value found for a contact resource when the contact was initialized.
{\tt resource-name} is the name of a resource defined in the resource
specification list for the {\tt contact}'s class or one of its superclasses.
\index{resource, specification}

}\end{flushright}

{\samepage
{\large {\bf default-resources \hfill Function}} 
\index{default-resources function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & default-resources & \\ 
& (contact\\
& class \\
& \&optional & resource-name) \\
(declare &(values  & resource-plist)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns the default values for {\tt contact} resources  of the given {\tt
class} (and, optionally, with the given {\tt resource-name}). The return value is a
property list of the form {\tt (\{{\em resource-name value}\}*)}. Each {\tt value}
is determined by the contents of the resource database (given by the value of the special variable {\tt
*database*}) and by the resource specification list of the {\tt contact}'s class
\index{*database*}\index{variables, *database*}, using  the same algorithm employed by the {\tt make-contact}
function
\index{make-contact function}(see Section~\ref{ch:creation}).

If {\tt contact} is a string, then it is assumed to be a host name.  In this
case, resources are returned for the default {\tt root} of a {\tt
contact-display} connected to this host.

}\end{flushright}


\SAMEL{Contact Resources}{ch:contact-class-resources}

Every contact has a set of resources which are initialized automatically
when the contact is created by the {\tt make-contact} function (see
Section~\ref{ch:creation}).\index{make-contact function}
If initial values for contact resources are not given as arguments to
{\tt make-contact}, then initial values are looked up in the resource
database given by the value of the special variable {\tt
*database*}.\index{variables, *database*}

Two types of resources may be associated with a contact. {\bf Class
resources} are determined by the contact class. Class resources are
defined by a {\tt :resources} option in the {\tt defcontact} form
defining the contact class.\index{defcontact macro}
The {\tt class-resources} function may be used to return a list of
contact class resources.

{\samepage
{\large {\bf class-resources \hfill Function}} 
\index{class-resources function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & class-resources & \\ 
& (class\\
& \&optional & full-p) \\
(declare &(values  & resources)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns the resource specification list for the given contact {\tt class}. If
{\tt full-p} is non-{\tt nil}, then the full resource specification list is
returned; otherwise, a list of resource names is returned.

}\end{flushright}

A contact may also have {\bf constraint
resources}\index{resource, constraint} which are determined by the class
of the contact's parent. Constraint resources are
defined by a {\tt :constraints} option in the {\tt defcontact} form
defining the parent class.\index{defcontact macro}
The {\tt class-constraints} function may be used to return the list of
constraint resources defined by a contact class.

Constraint resources allow a parent composite to ``attach'' resources to
its children without the knowledge of the children themselves.  More
precisely, the set of constraint resources belonging to a contact is
defined by the programmer of the {\em parent} class, not the programmer
of the contact's class.  Constraint resources are typically used to
control the parent's geometry management policy. The {\tt
contact-constraint} macro may be used to return or change the value of a
contact constraint resource. 

{\samepage
{\large {\bf class-constraints \hfill Function}} 
\index{class-constraints function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & class-constraints & \\ 
& (class\\
& \&optional & full-p) \\
(declare &(values  & resources)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns the constraint resource specification list for the given contact
{\tt class}. If
{\tt full-p} is non-{\tt nil}, then the full resource specification list is
returned; otherwise, a list of resource names is returned.

}\end{flushright}

{\samepage
{\large {\bf contact-constraint \hfill Macro}} 
\index{contact-constraint macro}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmacro & contact-constraint & \\ 
& (contact\\
& resource-name) \\
(declare & (type contact & contact)\\
         & (type symbol  & resource-name))\\
(declare &(values  & constraint-value)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns or (with {\tt setf}) changes the value of the given constraint
resource of the {\tt contact}.

}\end{flushright}



\CHAPTERL{Interactive Streams}{ch:interactive-stream}
CLUE defines a {\bf interactive stream contact}\index{interactive-stream}, an object
which behaves like
a Common Lisp input/output character stream.  An interactive stream
contact is an instance of the contact class {\tt interactive-stream} and may
be given by the application programmer as a stream argument to Common
Lisp I/O functions such as {\tt read},
{\tt listen}, {\tt prin1}, etc. The fundamental interface to {\tt
interactive-stream} objects consists of methods which implement the basic Common Lisp
character stream operations (see \cite{cltl}, Chapter 22) but whose details are
implementation-dependent.
\index{classes, interactive-stream}
  
\LOWERL{Interactive Stream Input}{ch:interactive-stream-input}
\index{interactive-stream, input from}
Character input from an {\tt interactive-stream} is implemented by the following
methods. In turn, these methods are implemented using operations on the
associated {\tt contact-display} object. See Section~\ref{ch:multiple-stream-input}.
 
{\samepage
{\large {\bf stream-read-char \hfill Method, interactive-stream}}
\index{interactive-stream, stream-read-char method}
\index{stream-read-char method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & stream-read-char & \\
& ((interactive-stream  &interactive-stream))\\
(declare &(values &character)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Reads the next character object from the {\tt interactive-stream}.

}\end{flushright}

{\samepage
{\large {\bf stream-read-line \hfill Method, interactive-stream}}
\index{interactive-stream, stream-read-line method}
\index{stream-read-line method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & stream-read-line & \\
& ((interactive-stream  &interactive-stream)\\
& \&rest & make-array-options)\\
(declare &(values &string)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Reads character objects from the {\tt interactive-stream}, up to and including the
next {\tt \#$\backslash$newline} character, and returns them as a string
(without the {\tt \#$\backslash$newline}). If given, the {\tt
make-array-options} arguments are passed to {\tt make-array} when
the returned string is created.

}\end{flushright}


{\samepage
{\large {\bf stream-unread-char \hfill Method, interactive-stream}}
\index{interactive-stream, stream-unread-char method}
\index{stream-unread-char method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & stream-unread-char & \\
& ((interactive-stream  &interactive-stream)\\
& character))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Unreads the character object. {\tt char} will be the next character read by
{\tt stream-read-char}.

}\end{flushright}


{\samepage
{\large {\bf stream-peek-char \hfill Method, interactive-stream}}
\index{interactive-stream, stream-peek-char method}
\index{stream-peek-char method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & stream-peek-char & \\
& ((interactive-stream  &interactive-stream)\\
& peek-type)\\
(declare &(values &character)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns the character object which would be returned by {\tt stream-read-char} but does
not remove it from the input buffer. If {\tt peek-type} is {\tt t}, {\tt
stream-peek-char} skips over any whitespace characters, removing them from the
input buffer, and returns the next character.

}\end{flushright}



{\samepage
{\large {\bf stream-listen \hfill Method, interactive-stream}}
\index{interactive-stream, stream-listen method}
\index{stream-listen method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & stream-listen & \\
& ((interactive-stream  &interactive-stream))\\
(declare &(values &boolean)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns {\tt nil} if no character is immediately available from the
{\tt interactive-stream}. Otherwise, the next character is returned, as if {\tt
stream-peek-char} had been called.}

\end{flushright}

{\samepage
{\large {\bf stream-clear-input \hfill Method, interactive-stream}}
\index{interactive-stream, stream-clear-input method}
\index{stream-clear-input method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & stream-clear-input & \\
& ((interactive-stream  &interactive-stream)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Clears any buffered characters received the {\tt interactive-stream}. Returns {\tt
nil}.
 
}
\end{flushright}

{\samepage
{\large {\bf stream-rubout-handler \hfill Method, interactive-stream}}
\index{interactive-stream, stream-rubout-handler method}
\index{stream-rubout-handler method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & stream-rubout-handler & \\
& ((interactive-stream  &interactive-stream)\\
& options\\
& function\\
&\&rest & arguments))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Applies the input {\tt function} to the {\tt arguments} inside an environment in
which the input buffer may be edited by user commands. {\tt options} is a list of rubout
handler options. The value of {\tt function} is returned.
 
}
\end{flushright}

{\samepage
{\large {\bf with-input-editing \hfill Macro, interactive-stream}}
\index{interactive-stream, with-input-editing macro}
\index{with-input-editing macro}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmacro & with-input-editing & \\
& (stream \\
& \&rest & options)\\
& \&body  & body)
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Executes the {\tt body} inside an environment which allows user editing
of input from {\tt stream}. If {\tt stream} is an {\tt
interactive-stream}, then the {\tt stream-rubout-handler}
method is used for input operations. The {\tt options} arguments are rubout
handler options. 
 
}
\end{flushright}


\SAME{Interactive Stream Output}
Character output to an {\tt interactive-stream} is implemented by the following
methods.

{\samepage
{\large {\bf stream-write-char \hfill Method, interactive-stream}}
\index{interactive-stream, stream-write-char method}
\index{stream-write-char method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & stream-write-char & \\
& ((interactive-stream  &interactive-stream)\\
& character)\\
(declare &(values &character)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Outputs the {\tt character} to the {\tt interactive-stream} and returns the {\tt
character}.
 
}
\end{flushright}

{\samepage
{\large {\bf stream-write-string \hfill Method, interactive-stream}}
\index{interactive-stream, stream-write-string method}
\index{stream-write-string method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & stream-write-string & \\
& ((interactive-stream  &interactive-stream)\\
& string\\
& \&optional & start \\
&            & end)\\
(declare &(values &string)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Outputs characters in the {\tt string} to the {\tt interactive-stream} and returns
the {\tt string}. The {\tt start} and {\tt end} arguments, if given, indicate a
substring that is to be output.
 
}
\end{flushright}

{\samepage
{\large {\bf stream-fresh-line \hfill Method, interactive-stream}}
\index{interactive-stream, stream-fresh-line method}
\index{stream-fresh-line method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & stream-fresh-line & \\
& ((interactive-stream  &interactive-stream))\\
(declare &(values &boolean)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Outputs a {\tt \#$\backslash$newline} to the {\tt interactive-stream} if and only if
the {\tt interactive-stream} is not already at the beginning of a new line. Returns non-{\tt
nil} if a {\tt \#$\backslash$newline} was output and {\tt nil} otherwise.
 
}
\end{flushright}

{\samepage
{\large {\bf stream-clear-output \hfill Method, interactive-stream}}
\index{interactive-stream, stream-clear-output method}
\index{stream-clear-output method}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defmethod & stream-clear-output & \\
& ((interactive-stream  &interactive-stream))\\
(declare &(values &nil)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Aborts any outstanding output operation on the {\tt interactive-stream} and returns
{\tt nil}.
 
}
\end{flushright}

\SAMEL{Input From Multiple Streams}{ch:multiple-stream-input}
\index{interactive-stream, input from}
\index{contact-display, input from interactive streams}
Multiple {\tt interactive-stream} contacts can be created for the same
{\tt contact-display}. In
this case, character input from the user to all such {\tt
interactive-stream} contacts is collected in a single keyboard
buffer owned by the {\tt contact-display}. When a Common Lisp stream input
function operates on an {\tt interactive-stream}, characters are returned from
the {\tt contact-display}'s keyboard buffer. Thus,
stream input from an {\tt interactive-stream} is implemented by operations on the
{\tt contact-display} object (see Section~\ref{ch:interactive-stream-input}).

{\samepage
{\large {\bf read-character \hfill Function, contact-display}}
\index{contact-display, read-character function}
\index{read-character function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & read-character & \\
& (contact-display)\\
(declare &(values &character)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Reads the next character object from the keyboard buffer of the {\tt
contact-display}. If the keyboard buffer is empty, then this function
waits until the next character for the keyboard buffer arrives.

}\end{flushright}


{\samepage
{\large {\bf unread-character \hfill Function, contact-display}}
\index{contact-display, unread-character function}
\index{unread-character function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & unread-character & \\
& (contact-display\\
& char))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Unreads the character object and returns it to the keyboard buffer of the
{\tt contact-display}. {\tt char} will be the next
character read by {\tt read-character}.

}\end{flushright}


{\samepage
{\large {\bf peek-character \hfill Function, contact-display}}
\index{contact-display, peek-character function}
\index{peek-character function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & peek-character & \\
& (contact-display)\\
(declare &(values &character)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns the character object which would be returned by {\tt read-character} but does
not remove it from the keyboard buffer of the {\tt contact-display}.

}\end{flushright}



{\samepage
{\large {\bf listen-character \hfill Function, contact-display}}
\index{contact-display, listen-character function}
\index{listen-character function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & listen-character & \\
& (contact-display)\\
(declare &(values &boolean)))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Returns {\tt nil} if and only if the keyboard buffer of the {\tt
contact-display} is empty. Otherwise, the next character in the keyboard buffer
is returned (but not removed).

}\end{flushright}

{\samepage
{\large {\bf clear-characters \hfill Function, contact-display}}
\index{contact-display, clear-characters function}
\index{clear-characters function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & clear-characters & \\
& (contact-display))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Removes any buffered characters from the keyboard buffer of the {\tt
contact-display}. Returns {\tt nil}.
 
}
\end{flushright}

{\samepage
{\large {\bf append-characters \hfill Function, contact-display}}
\index{contact-display, append-characters function}
\index{append-characters function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & append-characters & \\
& (contact-display\\
& chars))
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
{\tt chars} may be either a character or a string. Appends the characters
to the keyboard buffer of the {\tt contact-display}.
 
}
\end{flushright}


\SAME{Stream I/O Model}
\index{stream I/O model}\index{input, models}
In the stream I/O model, an interactive application exchanges character data
with an {\tt interactive-stream} contact\index{interactive-stream}. 
The stream I/O model represents applications which use a simple character-based
style of user interaction and do not rely upon additional input from
pointer devices.  Such applications have the following generic structure.
\begin{itemize}
\item Create and open a stream.
\item Perform application initialization.
\item Read a command from the stream and execute it. 
\item Repeat the previous step until the
application terminates.
\end{itemize}
No explicit references to a {\tt contact-display} object are necessary. The
stream I/O model is implemented in terms of the more basic event loop model,
\index{event loop model}
using a {\tt contact-display} object which is created automatically. 

The {\tt make-interactive-stream} function creates and returns an {\tt interactive-stream} contact for
use by a stream I/O application.

{\samepage
{\large {\bf make-interactive-stream \hfill Function}} 
\index{make-interactive-stream function}
\index{interactive-stream, make-interactive-stream function}
\begin{flushright} \parbox[t]{6.125in}{
\tt
\begin{tabular}{lll}
\raggedright
(defun & make-interactive-stream & \\ 
& (\&rest & keywords\\
&\&key & (type 'interactive-stream)\\
&\&allow-other-keys) \\
(declare &(values  & interactive-stream))) 
\end{tabular}
\rm

}\end{flushright}}

\begin{flushright} \parbox[t]{6.125in}{
Creates and returns an {\tt interactive-stream} contact. The {\tt
contact-display} associated with the {\tt interactive-stream} is created
automatically. {\tt keywords} may include any appropriate
keyword understood by {\tt
open-contact-display}\index{open-contact-display function}
and by {\tt make-contact} 
\index{make-contact function}
for the {\tt interactive-stream}.

}\end{flushright}


\begin{flushright} \parbox[t]{6.125in}{
{\tt type}
\begin{quote}
If given, {\tt type} must be a subclass of {\tt interactive-stream} which
specifies the type of {\tt interactive-stream} to return.
\end{quote}

}\end{flushright}


\CHAPTER{Acknowledgements} 
We are indebted to the following individuals, whose
careful reading and insightful suggestions have considerably improved the design
of CLUE and the clarity of this document.

\begin{tabular}{ll}
Jim Dutton      &       Texas Instruments \\
Tom Ekberg      &       Texas Instruments \\
Haruyuki Kawabe &       Nihon Unisys Ltd. \\
Mark Kirkpatrick &      Texas Instruments \\
Suzanne McBride &       Texas Instruments \\
Dan Stenger     &       Texas Instruments \\
\end{tabular}

By now, the use of CLUE software has grown beyond the scope of our own efforts
and has benefited from the contributions of many other programmers.  We would
particularly like to thank the following CLUE users for helping to make the
public implementation of CLUE more useful for all of us.

\begin{tabular}{ll}
Martin Dragomirecky	& General Electric CRD\\
Phil Dyskstra           & U.S. Army, Ballistics Research Laboratory \\
Dan Golan               & Convex Computer Corporation \\
Patrick Hogan           & Texas Instruments \\
Craig Timmerman         & Texas Instruments \\
Yvo Van Wezemael        & German National Research Laboratory for Computer Science\\
\end{tabular}


%
%
%
%
%
%
%
%
\begin{thebibliography}{9}

\bibitem{clos} Bobrow, Daniel G., et al. The Common Lisp Object System
Specification (X3J13-88-002). American National Standards Institute, June,
1988.

\bibitem{xlib} Gettys, Jim, et al. Xlib -- C Language X Interface, Version
11, Revision 3.

\bibitem{Xt} McCormack, Joel, et al. The X-Toolkit Intrinsics, Version
11, Revision 3.

\bibitem{pfaff-uims} Pfaff, G.E., Ed. {\em User Interface Management Systems}.
Springer-Verlag, Berlin, 1985.

\bibitem{icccm} Rosenthal, David S. H. X11 Inter-Client Communication Conventions
Manual, Public Review Draft (December 8, 1988).


\bibitem{x-protocol} Scheifler, Robert W. The X Window System Protocol, Version
11, Revision 3.

\bibitem{x-window-system} Scheifler, Robert W. and Gettys, Jim. The X Window
System. {\em ACM Transactions on Graphics}, Vol. 5, No. 2 (April 1986).

\bibitem{clx} Scheifler, Robert W., et al. CLX Interface
Specification, Version 4 (September 1987).

\bibitem{cltl} Steele, Guy. {\em Common LISP: The Language}. Digital Press,
Burlington, MA, 1984.


\end{thebibliography}


\begin{theindex}
\input{clue.index}
\end{theindex}

\end{document}


